开发人员效率

Developer Productivity

重构的主要目标之一是生成更易于理解的代码。在推理过程中简化密集的解决方案不仅可以帮助您更好地了解代码的作用，还可以帮助您的后续人员做同样的事情。您可以轻松理解的代码绝对可以提升团队中每个人的水平，无论他们的任期或经验水平如何。

One of the primary goals of refactoring is yielding code that is easier to understand. Simplifying a dense solution as you reason through it not only helps you gain a better grasp of what the code is doing, it also helps everyone who comes after you do the same. Code you can easily comprehend elevates absolutely everyone on your team, no matter their tenure or experience level.

如果您是团队中的资深工程师，您往往对代码库的某些部分非常熟悉，但是随着代码库的增长，越来越多的部分对您来说并不熟悉，并且您的代码越来越有可能对这些部分产生依赖。想象一下，您正在实现一个新功能，在将解决方案贯穿整个系统时，您会从您非常熟悉的代码冒险进入不熟悉的领域。如果您不熟悉的领域得到很好的维护，并定期重构以考虑不断变化的产品需求和错误修复，您将能够缩小更改的理想位置，并更快地找到轻松的解决方案。如果代码随着时间的推移而恶化，不断积累不完整的错误修复并不断膨胀，您将花费成倍增加的时间仔细阅读每一行，首先尝试了解代码在做什么以及它是如何工作的，然后才能花时间推理出可接受的解决方案。 （将其他人拖入折磨代码的兔子洞并不罕见，无论是与您一起工作的另一位工程师，还是熟悉代码来回答您的问题的人。）

If you are a tenured engineer on the team, you tend to be very familiar with some parts of the codebase but, as the codebase grows, more and more parts are unfamiliar to you, and your code is increasingly likely to develop dependencies on those parts. Imagine that you’re implementing a new feature and in weaving your solution through the system, you venture from code you know rather well to unfamiliar territory. If the area unknown to you is well maintained and regularly refactored to take into account evolving product requirements and bug fixes, you’ll be able to narrow down the ideal location for your change and intuit an effortless solution much more quickly. If the code has instead deteriorated over time by accruing patchy bug fixes and ballooning in length, you’ll spend exponentially more time wading through each line, trying first to understand what the code is doing and how it’s doing it before you’re able to spend any time reasoning through an acceptable solution. (It’s not uncommon to drag someone else into the tortured-code rabbit-hole, whether it’s another engineer working alongside you or one who’s intimately familiar with the code to answer your questions.)

让我们换个场景。如果另一个团队的同事不熟悉您团队的代码，不得不尝试阅读它，会怎么样？他们会很容易地理解它的工作原理吗？您是否更有可能期待问题和困惑的表情，还是要求进行代码审查？

Let’s flip the scenario. What if a colleague on another team who isn’t familiar with your team’s code had to take a stab at reading through it. Would they have an easy time understanding how it works? Are you more likely to expect questions and confused looks, or a request for code review?

如果您是团队中的新工程师，情况会怎样？也许您刚刚加入团队，或者您最近刚刚招募了某人，您可以借鉴他的经验。他们对代码库完全没有心理模型。他们对代码任何领域获得信心的能力与代码的可读性成正比。他们不仅能够有机地建立代码库中不同单元之间关系的准确心理表征，还能够推断出代码正在做什么，而无需标记队友以提出问题。（值得注意的是，知道何时以及如何向同事提问是一项非常重要的技能。学会评估在寻求帮助之前花多少时间建立自己的理解是困难的，但对于成长为开发人员至关重要。提问不是坏事，但如果您是团队中的资深工程师，并且感觉被问题轰炸，也许是时候编写一些文档并重构一些代码了。）

What if you were a new engineer on the team. Perhaps this was you just recently or maybe you recently onboarded someone to your team, whose experiences you can pull from. They have absolutely no mental model of the codebase. Their ability to gain confidence with any area of the code is directly proportional to the code’s legibility. Not only will they be able to organically build up an accurate mental representation of the relationships between different units in your codebase, they’ll be able to reason out what the code is doing without needing to tag teammates for questions. (It’s worth noting that knowing when and how to ask questions of your colleagues is an incredibly important skill to hone. Learning to evaluate how much time is appropriate for you to build your own understanding before seeking help is difficult but critical to growing as a developer. Asking questions isn’t a bad thing, but if you’re the tenured engineer on the team and you’re feeling bombarded with them, maybe it’s time to write some documentation and refactor some code.)

在开发新事物时，我们都倾向于复制既定的模式。如果我们参考的解决方案清晰简洁，我们更有可能传播清晰简洁的代码。反之亦然：如果我们唯一可参考的解决方案是杂乱无章的，我们就会传播杂乱无章的代码。确保最佳模式是最普遍的模式对于与刚起步的开发人员建立积极的反馈循环尤为重要。如果他们经常接触的代码易于理解，他们会在自己的解决方案中效仿类似的重点。

We’re all prone to copying established patterns when developing something new. If the solutions we reference are clear and concise, we’re more likely to propagate clear and concise code. The converse is also true: if the only solutions we have as reference are cluttered, we’ll propagate cluttered code. Ensuring that the best patterns are the most prevalent ones is particularly crucial in establishing a positive feedback loop with developers who are just starting out. If the code that they interact with on a regular basis is easy to understand, they’ll emulate a similar focus in their own solutions.

识别错误

Identifying Bugs

追踪和解决错误是我们工作中必不可少的一部分（而且很有趣！）。重构可以成为完成这两项任务的有效工具！通过将复杂的语句分解成更小、更简单的部分，并将逻辑提取到新函数中，您既可以更好地了解代码的作用，又可以隔离错误。在积极编写代码时进行重构还可以使您更容易在开发过程的早期发现错误，从而完全避免错误。

Tracking down and solving bugs is a necessary (and fun!) part of our jobs. Refactoring can be an effective tool in accomplishing both of these tasks! By breaking up complex statements into smaller, bite-sized pieces, and extracting logic into new functions, you can both build up a better understanding of what the code is doing and, hopefully, isolate the bug. Refactoring as you are actively writing code can also make it easier to spot bugs early in the development process, allowing you to avoid them altogether.

想象一下这样的场景：几个小时前，您的团队将一些新代码部署到生产环境中。一些更改嵌入在几个每个人都害怕修改的文件中：代码无法阅读，并且包含大量可能出现的错误。不幸的是，您的测试没有涵盖许多极端情况之一，客户服务人员联系您，告知用户开始遇到的棘手错误。您和您的团队立即开始深入研究，并很快意识到，正如预期的那样，错误位于代码中最可怕的部分。值得庆幸的是，您的队友能够一致地重现问题，并且您们一起编写了一个测试来断言正确的行为。现在您必须缩小错误范围。您采取有条不紊的步骤来分解棘手的代码：将冗长的单行代码转换为简洁的多行语句，并将一些条件代码块的内容迁移到单个函数中。最终，您找到了错误。现在代码已经简化，您可以快速修复它，运行测试以验证它是否有效，并将修复程序发送给您的客户。胜利！

Consider the scenario in which your team deployed some new code to production a few hours ago. A few of the changes were embedded in a handful of files that everyone fears modifying: the code is impossible to read and contains a minefield of bugs waiting to happen. Unfortunately, your tests didn’t cover one of many edge cases and someone from customer service reaches out about a pesky bug users are starting to run into. You and your team immediately start digging in and quickly realize that the bug is, as expected, in the scariest part of the code. Thankfully, your teammate’s able to reproduce the problem consistently and, together, you write a test to assert the correct behavior. Now you have to narrow down the bug. You take methodical steps to break down the hairy code: you convert lengthy one-liners into succinct, multiline statements and migrate the contents of a few conditional code blocks into individual functions. Eventually, you locate the bug. Now that the code’s been simplified, you’re able to fix it swiftly, run the test to verify that it works, and ship a fix to your customers. Victory!

对于客户来说，有时错误只是小麻烦，但有时，错误可能会阻止客户使用您的应用程序。虽然更具破坏性的错误通常需要紧急补救，但您的团队必须能够快速解决所有严重程度的错误，以让用户满意。在维护良好的代码库中工作可以大大减少开发人员需要解决和修复错误的时间，当它在创纪录的时间内交付生产时，您会感到高兴。

To the customer, sometimes bugs are only a minor nuisance, but other times, bugs can prevent the customer from using your application altogether. While more disruptive bugs generally require urgent remediation, it’s imperative that your team be able to solve bugs of all severity levels quickly to keep users happy. Working in a well-maintained codebase can dramatically decrease the time developers need to hone in on and fix a bug, delighting you when it’s shipped to production in record time.

严重倒退

Serious Regressions

重构未经测试的代码非常危险，因此极不建议这么做。即使配备了最全面、最复杂的测试套件的开发团队仍然会在生产中出现错误。为什么？每次更改（无论大小）都会以可衡量的方式破坏系统的平衡。我们力求尽可能减少破坏，但只要我们更改系统，就有可能导致无法预料的回归。在重构代码库中极其可怕、令人费解的角落时，引入严重的回归尤其令人担忧。代码库的这些区域通常处于当前状态，因为它们有足够的时间来恶化。在快速发展的公司中，它们通常既是应用程序运行不可或缺的部分，也是测试最少的部分。尝试理清这些文件或功能就像试图毫发无损地穿过雷区一样 — — 这是可能的，但非常危险。

Refactoring untested code is very dangerous and highly discouraged. Development teams equipped with the most thorough, sophisticated testing suites still ship bugs to production. Why? With every change, large or small, we disrupt the equilibrium of the system in a measurable way. We strive to cause as little disruption as possible, but whenever we alter our systems, there is a risk that it might lead to unanticipated regression. As we refactor the exceptionally frightening, puzzling corners of our codebase, introducing a serious regression is of particular concern. These areas of the codebase are frequently in their current state because they’ve had plenty of time to deteriorate. At fast-growing companies, they are also frequently both integral to how your application works and the least tested. Attempting to detangle these files or functions can feel like trying to walk across a minefield unscathed—it’s possible, but very dangerous.

挖掘潜伏的漏洞

Unearthing Dormant Bugs

重构不仅能帮你识别错误，还能无意间发现潜在的错误。在这里，我将潜在的错误归类为最常因重构代码而暴露的回归。我们以 Simon's Dry Cleaners 为例进行说明。该企业已开始以相同的交货节奏订购大批量的清洁产品，以便从供应商那里获得更好的交易。不幸的是，主店面后面没有太多空间来存放产品，因此 Simon's 决定开始将箱子堆放在离装卸码头门更近的地方。经过几周的降雨，团队注意到离门最近的一些箱子被打湿了，散架了。店主注意到后门密封性不好，在潮湿的日子里水会渗进来。Simon's 从未遇到过将物资存放在装卸码头门附近的问题，因为他们以前从未这样做过；实施新的存储模式暴露了他们基础设施中的一个关键缺陷，否则他们可能永远不会发现这个缺陷。

Just as refactoring can help you identify bugs, it can unintentionally unearth dormant bugs. Here, I classify dormant bugs as regressions that are most commonly exposed by restructuring code. We’ll revisit Simon’s Dry Cleaners to illustrate. The business has started ordering cleaning products in bigger batches at the same delivery cadence to unlock a better deal from the supplier. Unfortunately, there’s not much room to store the products in the back of the main storefront, so Simon’s decides to start stacking boxes closer to the loading dock door. After a few weeks of rain, the team notices that some of the boxes closest to the door are wet and falling apart. The owner notices that the back door is poorly sealed and allows water to seep through on wet days. Simon’s had never encountered a problem with storing supplies close to the loading dock door because they’d simply never done it before; exercising a new storage pattern exposed a critical flaw in their infrastructure, which they might have never discovered otherwise.

范围蔓延

Scope Creep

重构有点像吃布朗尼蛋糕：前几口味道很好，但很容易忘乎所以，不小心吃掉整整一打。当你吃完最后一口时，你会感到一丝后悔，也许还有点恶心。当你进行集中、局部的更改时，体验到立竿见影的、极为显著的改进，这是一种非常有益的体验！很容易忘乎所以，让更改的表面积超出合理的范围。我所说的合理范围是什么意思？根据代码库，这可以指单个功能区域或一小段相互依赖的库集。理想情况下，重构的代码仅限于另一个开发人员可以在单个变更集内舒适地审查的一组变更。

Refactoring can be a little bit like eating brownies: the first few bites are delicious, making it easy to get carried away and accidentally eat an entire dozen. When you’ve taken your last bite, a bit of regret and perhaps a twinge of nausea kick in. Experiencing immediate, highly significant improvements when you’re making focused, localized changes is incredibly rewarding! It’s easy to get carried away and allow the surface area of your changes to exceed reasonable bounds. What do I mean by reasonable bounds? Depending on the codebase, this can refer to a single functional area or a small, interdependent set of libraries. Ideally, the refactored code is limited to a set of changes another developer can comfortably review within a single changeset.

在规划更大规模的重构工作时，尤其是可能需要几个月甚至更长时间的重构工作时，绝对有必要严格控制范围。在重构小范围（几行代码、单个函数）时，我们都会遇到意想不到的怪癖；虽然我们可以持续地链接一些增强功能来有效地处理这些新怪癖，但在处理较大的范围时，这种方法会变得很危险。计划重构的范围越大，您遇到的可能没有预料到的问题就越多。这并不会让您成为一个糟糕的程序员，只是让您变得平易近人。通过坚持明确的计划，您可以降低导致严重回归或遇到潜在错误的可能性，并提高生产力。持续、有条不紊的重构工作已经很困难了；不断变动的目标只会让它们无法实现。

When mapping out a larger refactoring effort, especially one that might take several months or more, it’s absolutely imperative to keep a tight scope. We all run into unexpected quirks when refactoring small surface areas (a few lines of code, single functions); while we can sustainably chain a few enhancements to handle these new quirks effectively, this approach becomes dangerous when tackling a significant surface area. The larger the surface area of the planned refactor, the more problems you’ll encounter that you likely haven’t anticipated. That doesn’t make you a bad programmer, it simply makes you human. By keeping to a well-defined plan, you decrease the chances of causing a serious regression or running into dormant bugs, and promote productivity. Sustained, methodical refactoring efforts are already difficult; having a moving goalpost simply makes them unachievable.

不必要的复杂性

Unnecessary Complexity

开始时要小心不要过度设计，并愿意修改你的初始计划。主要目标应该是编写人性化的代码，即使以牺牲原始设计为代价。如果重点放在解决方案而不是流程上，那么你的应用程序最终会比最初更加做作和复杂的可能性就更大。所有级别的重构都应该是迭代的。通过朝着一个方向采取小而慎重的步骤并在每次迭代中保持现有行为，你能够更好地专注于你的最终目标。当你只处理屏幕上足够的代码而不是一次处理三十多个库时，这要容易得多。当我们计划一个新项目时，我们大多数人通常会尽力制定详细的规范文档和执行计划。即使重构工作量很大，重要的是要清楚地了解完成后的代码应该是什么样子。

Be wary of over designing at the start and be open to modifying your initial plan. The primary goal should be to produce human-friendly code, even at the cost of your original design. If the laser focus is on the solution rather than the process, there’s a greater chance your application will end up more more contrived and complicated than it was in the first place. Refactoring at all levels should be iterative. By taking small, deliberate steps in one direction and maintaining existing behavior at each iteration, you’re better able to maintain focus on your ultimate goal. This is much easier to do when tackling only enough code as fits on your screen rather than three dozen libraries at a time. When we plan a new project, most of us generally try our best to develop a detailed specification document and execution plan. Even with a large refactoring effort, it’s important to have a good sense of what the resulting code should look like upon completion.

小范围

Small Scope

当您想要重构一小段经过充分测试的代码时，应该没有什么事情会阻碍您。除非您不确定重构后的解决方案是否比其前身有客观改进，或者您担心更改会影响太大的范围，否则这可能是值得的。仔细编写一些提交并开始进行更改！我们将在本章后面看到一个明显属于此类别的示例。

When looking to refactor a small, straightforward section of well-tested code, there should be very little holding you back. Unless you’re uncertain that your refactored solution is an objective improvement to its predecessor, or you’re fearful the change affects too large of a surface area, it’s likely a worthwhile endeavor. Carefully craft a few commits and get your changes rolling! We’ll see an example that clearly falls into this category later in this chapter.

代码复杂性严重阻碍开发

Code Complexity Actively Hinders Development

有时，我们不得不冒险进入代码库中我们害怕的部分。每次我们阅读代码时，我们的眉头都会皱起，我们的心会怦怦直跳，我们的神经元开始放电。然后，我们就必须咬紧牙关，深入研究，做出我们想要做出的改变。但在压力下进行开发肯定会无意中造成更多问题。当你如此专注于做正确的事情，脑子里想着问题的各个方面时，你就有可能忘记你的实际目标。当你的心思在别处时，你如何才能充分实现那个目标？

There are times when we have to venture into parts of our codebase we fear. Every time we read over the code, our brows furrow, our hearts pound, our neurons start firing. Then comes the moment when we have to bite the bullet, dig in, and make the change we came to make. But developing under duress is a surefire way to inadvertently cause more problems. When you’re so hyper-focused on doing precisely the correct thing, holding the many dimensions of the problem in your head, you risk losing sight of your actual goal. How can you execute adequately on that goal when your mind is elsewhere?

如果代码的这个特定部分还没有给我们带来麻烦，我们通常会冒险尝试。如果代码已经给我们或我们的队友带来麻烦（有时不止一次），那么现在对代码进行彻底检查以防止将来出现错误的风险可能大于让它继续停留在当前状态的风险。如果您不确定天平会向哪个方向倾斜，请与您的队友讨论并收集一些数据，了解过去六个月内发现的错误数量，以便您可以追溯到代码库的这一部分。

If this particular section of the code hasn’t bitten us yet, we’ll often take our chances and make it. If it’s bitten us or a fellow teammate already (sometimes more than once), the risk involved in taking a scalpel to the code now to prevent future mistakes might outweigh the risk of letting it linger in its current state any longer. If you’re unsure which way the scales tilt, talk it over with your teammates and collect some data on the number of bugs caught in the past six months that you can trace back to this part of the codebase.

产品需求的转变

Shift in Product Requirements

产品需求的急剧变化往往会导致代码的急剧变化。尽管我们努力为应用程序中的每个功能编写抽象、可扩展的解决方案，但我们无法预测未来；虽然我们的代码可能很容易适应小偏差，但它很少能完美适应较大的偏差。这些变化为我们提供了难得的业务相关机会，让我们重新回到绘图板并重新考虑我们的设计。

Drastic shifts in product requirements can frequently map to drastic shifts in code. As hard as we might try to write abstract, extendable solutions for each piece of functionality in our application, we can’t predict the future; and while our code might be easy to adapt for small deviations, it is seldom perfectly adaptable to larger ones. These shifts give us the rare business-related opportunity to go back to the drawing board and reconsider our design.

您可能认为这些转变不可能保留行为。给定相同的输入，现在我们必须提供不同的输出！这怎么可能是重构的好时机呢？如果您当前的代码不能很好地满足新要求，那么您必须想出一个解决方案，继续支持今天的功能，并无缝支持明天的功能。您可以先重构代码，然后（只有这样！）在其上实现新功能。这样，您就可以继续设定高质量代码的标准，充分利用重构的所有好处，同时支持业务目标。再说一次，这是双赢！

You may be thinking that these sorts of shifts can’t possibly preserve behavior. Given the same inputs, now we must provide different outputs! How is this an opportune time for refactoring? If your code in its current state doesn’t lend itself well to the new requirements, you must come up with a solution that continues to support today’s functionality and will seamlessly support tomorrow’s. You can make a case for refactoring your code first, and then (and only then!) implement the new functionality atop it. This way, you continue to set a standard of high-quality code, cashing in all the benefits of refactoring, all the while supporting business objectives. Again, it’s a win, win, win!

表现

Performance

提高绩效可能是一项艰巨的任务；您必须首先深入了解现有行为，然后能够确定可以使用哪些杠杆来将天平向积极的方向倾斜。从头开始（或首先构建一个）将最有助于您做到这一点。正确隔离您已确定的杠杆，以便更容易操纵它们而不会产生下游效应的风险，这也是关键。

Improving performance can be a difficult task; you must first build a deep understanding of the existing behavior and then be able to identify which levers you might be able to use to tilt the scales in a positive direction. Beginning with a clean slate (or building one as a first step) will best enable you to do that. Properly isolating the levers you’ve identified so that they are easier to manipulate without risk of downstream effects is also key.

为此目的的重构在一个重要方面是独一无二的：它不能确保结果代码更易于理解。有时，我们会通读代码库，并看到一长串警告其下方代码的注释块。根据我的经验，大多数这样的注释块都会提醒读者注意一个（或多个）复杂情况：奇怪的应用程序行为、临时解决方法和一个特殊的性能补丁。这些短篇故事开头的大部分性能改进都写得很巧妙，利用了对代码库的深刻理解，以此将受影响的表面积降到最低。这些“改进”更容易在较短的时间内退化，因此并不是重构旨在促进的可持续性的好例子。有价值的性能改进，值得纳入重构范畴的改进，是深刻而深远的；它们是有效大规模重构的例子。我们将在第二部分中更深入地介绍这些变化。

Refactoring for this purpose is unique in one important way: it does not ensure more approachable code as an outcome. Sometimes we’ll be reading through a codebase and come across a lengthy comment block warning about the code below it. In my experience, most of these comment blocks caution the reader about one (or more) complications: strange application behavior, temporary workarounds, and a peculiar performance patch. Most performance improvements prefaced by these short stories are written cleverly and leverage a deep understanding of the code base as a means of minimizing the surface area affected. These “improvements” are more susceptible to degradation over a shorter period and as such are not good examples of the sustainability that refactoring is meant to foster. The worthwhile performance improvements, the ones worthy of falling under the refactoring umbrella, are profound and far-reaching; they are examples of effective refactoring deployed at scale. We’ll cover these changes in greater depth in Part II.

使用新技术

Using a New Technology

在软件开发领域，我们经常采用新技术。无论是为了跟上行业的最新趋势，提高我们扩展到更多用户的能力，还是以新的方式完善我们的产品，我们都在不断评估新的开源库、协议、编程语言、服务提供商等。我们不会轻易决定使用新的东西；这部分是由于我们现有代码库中的集成成本。如果我们选择用新解决方案替换现有解决方案，我们必须制定弃用计划，确定所有受影响的调用站点并迁移它们（有时一次一个）。如果我们选择在未来采用一项新技术，我们必须确定高杠杆率的候选者以供早期采用，并制定计划将使用范围扩展到所有相关用例。

In the world of software development, we’re regularly adopting new technologies. Whether it’s to keep up with the newest trends in our industry, boost our ability to scale to more users, or mature our product in a new way, we’re perpetually evaluating new open-source libraries, protocols, programming languages, service providers, and more. Making the decision to use something new is not something we do lightly; this is partly due to the cost of integration within our existing codebases. If we opt to replace an existing solution with a new one, we have to craft a deprecation plan by identifying all affected callsites and migrating them (sometimes one at a time). If we opt to adopt a new technology moving forward, we have to identify high-leverage candidates for early adoption, with a plan to expand usage to all relevant use cases.

我不会一一列举使用新技术对系统产生的影响（影响方式有很多），但从这两种情况可以清楚地看出，每种情况都需要对当前系统进行仔细审核。幸运的是，审核可以揭示重构的绝佳机会！我想花点时间承认这是一个有争议的观点。由于采用新技术本身存在风险，其他开发人员可能会阻止您进行任何其他更改。但是，我坚信，将新事物引入系统的最糟糕方式是将其与巨大而混乱的事物放在一起。为了让它有最大的机会实现其目的，我认为最好先花时间清理它将接触的区域。

I won’t enumerate each of the ways using a new technology can affect your system (there are many), but it’s clear from these two scenarios that each requires a careful audit of your current system. Fortunately, an audit can reveal prime opportunities for refactoring! I want to take the time to acknowledge that this is a somewhat controversial opinion. Because of the risks involved with adopting a new technology alone, other developers may discourage you from making any other changes. However, I strongly believe that the worst way to introduce something new into your system is to stick it right in alongside a huge, tangled mess. To give it the best chance to fulfill its purpose, I think it’s best to take the time to clean up the areas it’ll come in contact with first.

我们可以轻松地将这一概念应用到西蒙干洗店。假设这家店最近订购了一些新型的、先进的、环保的干洗机器。在制定安装计划时，店主意识到他们现有的平面图存在严重的效率低下问题。员工必须沿着机器线一直走，才能从近三十英尺外的衣架上取下预先分类好的衣服。如果他们重新调整机器的方向，让员工只需走几英尺就能到达衣架，他们可能会在每个周期中节省几分钟。他们决定按照修改后的配置安装新机器。西蒙干洗店可能已经减少了对环境的影响，并提高了员工的工作效率。双赢！

We can easily apply this concept to Simon’s Dry Cleaners. Let’s say it just recently put in an order for some new state-of-the-art, eco-friendly dry cleaning machinery. In figuring out an installation plan, the owners realize that their existing floor plan has some serious inefficiencies. Employees have to walk all the way along the line of machines to pick up presorted garments from the racks nearly thirty feet away. If they reorient the machinery so that employees can walk just a few feet to reach the racks, they might shave a few minutes off of every cycle. They make the decision to install the new machines in the revised configuration. Simon’s may have decreased its impact on the environment and increased the productivity of their employees. Win, win!

为了好玩或无聊

For Fun or Out of Boredom

闭上眼睛，想象自己坐在电脑前。你正在看一个特别棘手的函数。它太长了；它试图做太多的事情。它的名字早已不再有意义地描述它的职责。你迫不及待地想修复它。你很想把它分成定义明确、简洁的单元，并使用更好的变量名。这会很有趣。但这是你现在可以做的最重要的事情吗？也许你的队友已经等了你几天的代码审查，或者你一直在推迟编写一些测试？如果你正在研究一些老旧的代码并对其进行修改以让自己开心，那么你可能会对自己（和你的队友）造成伤害。

Close your eyes for a minute and imagine yourself sitting in front of your computer. You’re looking at a particularly gnarly function. It’s too long; it tries to do too many things. Its name has long since ceased to describe its responsibility meaningfully. You’re itching to fix it. You’d love to split it up into well-defined, succinct units complete with better variables names. It’d be fun. But is it the most important thing you could be doing right now? Perhaps your teammate’s been waiting for your code review for a few days or you’ve been putting off writing some tests? If you’re digging into some crufty old code and shifting it around to keep yourself entertained, you might be doing yourself (and your teammates) a disservice.

很有可能，如果你只是为了好玩而进行重构，你就不会关注你的改变对周围代码、整个系统和你的同事的影响。当我们为了好玩而进行重构时，我们有不同的动机：我们更有可能使用更牵强的语言特性，或者尝试我们一直想尝试的全新模式。尝试新事物和锻炼编程能力是有时间和地点的，但重构不是那个时候。重构应该是一个深思熟虑的过程，重点是严格提供（理想情况下）最小的改变以获得最大的积极影响。

Chances are, if you’re refactoring for fun, you’re not focusing on the impact that your change will have on the surrounding code, the overall system, and your coworkers. We have different motivations when we’re refactoring for fun: we’re more likely to use more far-fetched language features or try out a brand new pattern we’ve been wanting to give a whirl. There is a time and place for trying new things and stretching our programming muscles, but refactoring isn’t that time. Refactoring should be a deliberate process where the focus is strictly on providing the (ideally) smallest change for the biggest positive impact.

因为你恰巧路过

Because You Happened to Be Passing By

想象一下：你写了一些代码，将其发布到生产环境，然后开始开发一个新功能。几个月后，你又回过头来扩展这个功能。不幸的是，它看起来和你最初写的代码完全不一样。无数个问题在你的脑海中闪过。这里发生了什么？

Picture this: you write some code, ship it to production, and start working on a new feature. You come back to your code a few months later to expand on the feature. Unfortunately, it looks nothing like what you originally wrote. A million questions are racing through your mind. What happened here?

您可能已经成为“驱动重构者”的牺牲品。这种同事经验丰富，对如何编写代码有着深刻的见解。他们是其他工程师在设计决策方面咨询的对象。他们还具有在遇到他人代码时重写代码的不良倾向。他们认为这样做是在帮大家的忙。

You may have fallen prey to the drive-by refactorer. This is a coworker who is experienced enough to have developed some well-informed opinions about how to write code. They are someone whom other engineers consult with about design decisions. They also have an unfortunate tendency to rewrite others’ code as they encounter it. They think they’re doing everyone a favor by doing this.

您可能很想同意这一观点，但请考虑一下：如果这位工程师修改了他们不是活跃贡献者的代码库区域中的代码，则很可能降低了负责该代码的人员的生产力。当我们熟悉自己负责的代码时，我们的工作效率最高。当我们被要求快速解决问题时，无论是生产中的严重事故还是小错误，我们都会使用代码的心理模型来缩小可能存在问题的一组文件、类或函数的范围。如果我们打开编辑器，发现所有内容都不在我们之前的位置，我们就会迷失方向，无法快速解决问题。这会给我们的雇主带来巨大的成本，包括工程时间、客户服务时间，甚至可能造成业务损失。

You might be tempted to agree, but consider this: if this engineer modified code in an area of the codebase where they are not an active contributor, it’s likely they’ve decreased the productivity of those that are responsible for it. We are most productive when we are familiar with the code for which we are responsible. When we’re tasked with quickly resolving an issue, whether it is a serious incident in production or a small bug, we use our mental model of the code to narrow a set of files, classes, or functions where the problem might exist. If we open up our editor and find that nothing is where we left it, we’re disoriented and unable to fix the issue as quickly. This is incredibly costly to our employers in engineering hours, customer service hours, and potentially lost business.

不告诉原作者重构一事在两个方面都是不利的。首先，他们已经主动侵蚀了作者的信任。尽管我们试图将自己与代码分开，但我们总是会在自己编写的代码中留下一小点个人自豪感和所有权。我更希望有人能诚实地告诉我解决方案的缺点，并告诉我如何修复它，而不是在问题已经解决之后才发现问题。对于新工程师来说，这尤其有害。想象一下，你刚从学校毕业一年；有一天你上班却发现，你花了数周时间拼凑起来的代码已经被一个你从未交谈过的资深工程师在几个小时内重写了。感觉真不好。

Not telling the original author about the refactor is a disservice in two distinct ways. First, they have actively eroded the author’s trust. As much as we try to divorce ourselves from our code, we always leave a tiny piece of personal pride and ownership in the code that we’ve written. I’d much prefer if someone were honest with me about the shortcomings of my solution and shows me how to fix it rather than find out about the problems after they’ve already been addressed. This is particularly harmful when it comes to newer engineers. Imagine yourself just one year out of school; you come into work one day only to find that the code that you’d taken weeks to cobble together had been rewritten in a few hours by a much more senior engineer whom you’ve never talked to. It doesn’t feel great.

其次，他们可能不知道代码编写时的初始环境。当处理驱动重构者没有积极维护的代码时，这一点尤其麻烦。为什么这很重要？编程就是权衡；我们可以通过使用内存密集型数据结构来编写更快的解决方案，或者通过近似而不是进行精确计算来减少内存占用。同样，每一行“坏”代码都试图解决问题。通过盲目重构，您可能会成为原作者小心翼翼避免的错误或弱点的牺牲品。

Second, they may not be aware of the initial circumstances surrounding the code at the time it was written. This is particularly troublesome when dealing with code that the drive-by refactorer is not actively maintaining. Why is this important? Programming is all about trade-offs; we can write a faster solution by using a more memory-intensive data structure or reduce our memory footprint by approximating rather than making precise calculations. Likewise, every line of “bad” code attempted to solve a problem. By blindly refactoring it, you may fall prey to a bug or weakness the original authors were carefully trying to avoid.

不要成为被动的重构者，而要成为善意的重构者。很少重构您不主动维护的代码，并且当您这样做时，请确保您是在负责人员的意见下进行的。

Don’t be a drive-by refactorer, be a well-intentioned refactorer. Rarely refactor code that you are not actively maintaining, and when you do, make sure you’re doing it with the input of those responsible for it.

使代码更具扩展性

To Making Code More Extendable

许多重构大师都提倡将重构作为使代码更易于扩展的一种手段。虽然这可以成为良好重构的明显结果，但为了未来的可塑性而重写代码可能是不明智的。在没有清楚了解直接、切实的好处的情况下花时间进行重构可能是白费力气；您的更改可能不会在相当短的时间内产生回报，在最坏的情况下，也不会在代码的生命周期内产生回报。

Many refactoring gurus advocate for refactoring as a means to render code more readily extendable. While this can be a clear outcome of a good refactor, rewriting code for the sake of future malleability is likely unwise. Time spent refactoring without a clear understanding of the immediate, tangible wins might be a wasted effort; your changes might not pay off within a reasonably short period, nor, in the absolute worst case, within the lifetime of the code.

如果您可以对代码块进行足够的更改以推进项目，那么您可能不应该对其进行重构。大多数公司都有新功能需要开发和错误修复需要发布。一般来说，这些几乎总是具有更高的优先级。除非您有一套具体的目标，并且有令人信服的论据证明它将直接影响您公司的底线，否则您的管理链将不相信。但不要沮丧！我们将在接下来的章节中帮助您为重构建立业务案例。

If you can make adequate changes to a block of code to advance your project, you probably shouldn’t be refactoring it. Most companies have new features to develop and bug fixes to ship. Generally speaking, these are almost always of higher priority. Unless you have a concrete set of goals, and a compelling argument that it will directly affect your company’s bottom line, your management chain will be unconvinced. But don’t dismay! We’ll help you build a business case for refactoring in the coming chapters.

当你没有时间时

When You Don’t Have Time

比急需重构的代码更糟糕的是重构了一半的代码。处于不确定状态的代码会让与之交互的开发人员感到困惑。如果没有明确的时间点来完全重构代码，它就会呈现半永久性的混乱状态。读者在阅读重构中期的代码时，通常很难辨别要遵循的方向或实现，尤其是如果重构者没有留下任何评论。您甚至可能会对哪些代码将被长期采用做出错误的假设，并在即将弃用的块中实施必要的更改。这些错误会迅速堆积起来，导致您最初希望改进的代码更快、更严重地受到侵蚀。

The only thing worse than code in dire need of refactoring is code half-refactored. Code in limbo is confusing to developers interacting with it. When there is no clear point in time when the code will be fully refactored, it takes on semi-permanent disorder. It’s often difficult for the reader to discern the direction or implementation to follow when reading code mid-refactor, especially if the refactorer left no comments in their wake. You might even make an incorrect assumption about which code will be adopted long-term and implement a necessary change in a block that’s headed for deprecation. These kinds of mistakes pile up quickly, leading to faster, more serious erosion of the code you hoped to improve in the first place.

在着手重构某些东西时，请确保你有足够的时间来完成你的计划。如果没有，请尝试缩小你的更改范围，以便你仍然可以进行一些改进，但可以轻松地到达终点。不完整的重构所带来的暂时好处无法抵消未来开发人员与之交互的困惑和沮丧。

When setting out to refactor something, make sure you have enough time to see your plans through to completion. If not, try to scope down your changes so that you can still make some improvements but comfortably reach the finish line. No temporary benefits reaped from an incomplete refactor outweigh the confusion and frustration of future developers interacting with it.

简化条件

Simplifying Conditionals

首先，让我们简化一些if语句逻辑。我们可以通过提前返回函数结果（而不是评估每个分支并返回最终值）来轻松做到这一点。如果提供的最小值和最大值超出范围，我们也会提前返回，如示例 1-20, 100所示。

First, let’s simplify some of the if statement logic. We can easily do that by returning a result from the function early rather than evaluating every branch and returning a final value. We’ll also return early in the case that the provided minimum and maximum values fall outside the 0, 100 range, as shown in Example 1-2.

function checkValid(
  minimum,
  maximum,
  values,
  useAverage = false
) {

  if (minimum < 0 || maximum > 100) return false; 

  let min = Math.min(...values);
  let max = Math.max(...values);

  if (useAverage) {
    min = max = values.reduce((acc, curr) => acc + curr, 0)/values.length;
  }

  if (!(minimum <= min) || !(maximum >= max)) return false; 
  if (maximum >= max && minimum <= min) return true; 

  return false;
}

function checkValid(
  minimum,
  maximum,
  values,
  useAverage = false
) {

  if (minimum < 0 || maximum > 100) return false; 

  let min = Math.min(...values);
  let max = Math.max(...values);

  if (useAverage) {
    min = max = values.reduce((acc, curr) => acc + curr, 0)/values.length;
  }

  if (!(minimum <= min) || !(maximum >= max)) return false; 
  if (maximum >= max && minimum <= min) return true; 

  return false;
}

如果最小值或最大值超出范围，则提前返回。

Return early if the minimum or maximum is out of range.

尽可能尽早返回以简化逻辑。

Simplify the logic by returning early when we can.

现在我们开始有所进展了！让我们看看是否可以通过推理函数返回 false 的所有情况来进一步简化逻辑：计算出的最小值小于提供的最小值的情况，以及计算出的最大值大于提供的最大值的情况。我们可以通过提前失败并仅true在验证每个简单的失败情况后才返回结果来替换当前条件。示例 1-3说明了这些变化中的每一个。

Now we’re getting somewhere! Let’s see whether we can further simplify the logic by reasoning through all of the cases for which the function would return false: there’s the case where the calculated minimum is smaller than the provided minimum and the case where the calculated maximum is greater than the provided maximum. We can replace the current conditions by failing early and only returning a true result after verifying each of these simple failure cases instead. Example 1-3 illustrates each of these changes.

function checkValid(
  minimum,
  maximum,
  values,
  useAverage = false
) {

  if (minimum < 0 || maximum > 100) return false;

  let min = Math.min(...values);
  let max = Math.max(...values);

  if (useAverage) {
    min = max = values.reduce((acc, curr) => acc + curr, 0)/values.length;
  }

  if (min < minimum) return false; 
  if (max > maximum) return false; 
  return true; 
}

function checkValid(
  minimum,
  maximum,
  values,
  useAverage = false
) {

  if (minimum < 0 || maximum > 100) return false;

  let min = Math.min(...values);
  let max = Math.max(...values);

  if (useAverage) {
    min = max = values.reduce((acc, curr) => acc + curr, 0)/values.length;
  }

  if (min < minimum) return false; 
  if (max > maximum) return false; 
  return true; 
}

通过案例推理并每个if语句只有一个条件来简化逻辑。

Simplify logic by reasoning through the cases and only having one condition per if statement.

尽早失败并true仅当我们确定值有效时才返回。

Fail early and return true only if we’re certain that the values are valid.

提取魔法数字

Extracting Magic Numbers

我们的下一步是将内联数字（或魔法数字）提取到具有信息名称的变量中。我们还将重命名values为grades以便清晰起见。（或者，我们可以将它们定义为与函数声明相同范围内的常量，但现在我们先保持简单。）示例 1-4演示了这些说明。

Our next step will be to extract the inlined numbers (or magic numbers) into variables with informative names. We’ll also rename values to grades for clarity. (Alternatively, we could define these as constants within the same scope as the function declaration, but we’ll keep things simple for now.) Example 1-4 demonstrates these clarifications.

function checkValid(
  minimumBound, 
  maximumBound, 
  grades, 
  useAverage = false
) {

  // Valid assignments should never allow fewer than 0 points
  var absoluteMinimum = 0; 

  // Valid assignments should never exceed more than 100 possible points
  var absoluteMaximum = 100; 

  if (minimumBound < absoluteMinimum) return false; 
  if (maximumBound > absoluteMaximum) return false; 

  let min = Math.min(...grades);
  let max = Math.max(...grades);

  if (useAverage) {
    min = max = grades.reduce((acc, curr) => acc + curr, 0)/grades.length;
  }

  if (min < minimumBound) return false;
  if (max > maximumBound) return false;
  return true;
}

function checkValid(
  minimumBound, 
  maximumBound, 
  grades, 
  useAverage = false
) {

  // Valid assignments should never allow fewer than 0 points
  var absoluteMinimum = 0; 

  // Valid assignments should never exceed more than 100 possible points
  var absoluteMaximum = 100; 

  if (minimumBound < absoluteMinimum) return false; 
  if (maximumBound > absoluteMaximum) return false; 

  let min = Math.min(...grades);
  let max = Math.max(...grades);

  if (useAverage) {
    min = max = grades.reduce((acc, curr) => acc + curr, 0)/grades.length;
  }

  if (min < minimumBound) return false;
  if (max > maximumBound) return false;
  return true;
}

重命名参数来描述其作用。

Renaming the parameter to describe its role.

魔法数字的命名十分恰当，可以增加背景信息。

Magic numbers are appropriately named for added context.

通过将复杂的条件拆分为两个更简单的if语句来进一步简化逻辑。

Further simplifying logic by splitting up the complex conditional into two simpler if statements.

提取自包含逻辑

Extracting Self-Contained Logic

接下来，我们可以将平均值计算提取到一个单独的函数中，如示例 1-5所示。

Next, we can extract the average calculation into a separate function, as shown in Example 1-5.

function checkValid(
  minimum,
  maximum,
  grades,
  useAverage = false
){
  // Valid assignments should never allow fewer than 0 points
  var absoluteMinimum = 0;

  // Valid assignments should never exceed more than 100 possible points
  var absoluteMaximum = 100;

  if (minimumBound < absoluteMinimum) return false;
  if (maximumBound > absoluteMaximum) return false;

  let min = Math.min(...grades);
  let max = Math.max(...grades);

  if (useAverage) {
    min = max = calculateAverage(grades);
  }

  if (min < minimumBound) return false;
  if (max > maximumBound) return false;
  return true;
}

function calculateAverage(grades) { 
  return grades.reduce((acc, curr) => acc + curr, 0)/grades.length;
}

function checkValid(
  minimum,
  maximum,
  grades,
  useAverage = false
){
  // Valid assignments should never allow fewer than 0 points
  var absoluteMinimum = 0;

  // Valid assignments should never exceed more than 100 possible points
  var absoluteMaximum = 100;

  if (minimumBound < absoluteMinimum) return false;
  if (maximumBound > absoluteMaximum) return false;

  let min = Math.min(...grades);
  let max = Math.max(...grades);

  if (useAverage) {
    min = max = calculateAverage(grades);
  }

  if (min < minimumBound) return false;
  if (max > maximumBound) return false;
  return true;
}

function calculateAverage(grades) { 
  return grades.reduce((acc, curr) => acc + curr, 0)/grades.length;
}

将平均值计算提取到一个新函数中。

Extracted average calculation into a new function.

随着我们不断迭代解决方案，越来越明显的是，处理成绩平均值的逻辑似乎越来越不合适。接下来，我们将继续通过创建两个函数来改进我们的函数：一个函数验证成绩平均值是否在一组范围内，另一个函数验证一组中的所有成绩是否在最小值和最大值范围内。此时，我们可以通过多种方式将代码重新组织为更有针对性的函数。只要我们找到一种有效地分离两种不同情况的逻辑的方法，就没有正确或错误的答案。示例 1-6展示了进一步简化函数的一种方法checkValid。

As we iterate on our solution, it becomes more obvious that the logic to handle the average of the set of grades seems increasingly out of place. Next, we’ll continue to improve our function by creating two functions: one that verifies that the average of a set of grades fits within a set of bounds and another that verifies that all grades within a set occur within a minimum and a maximum value. We could reorganize the code into more focused functions at this point in a number of ways. There is no right or wrong answer so long as we’ve found a way to divorce the logic for the two distinct cases effectively. Example 1-6 shows one such way of further simplifying our checkValid function.

function checkValid(
  minimum,
  maximum,
  grades,
  useAverage = false
){

  // Valid assignments should never allow fewer than 0 points
  var absoluteMinimum = 0;

  // Valid assignments should never exceed more than 100 possible points
  var absoluteMaximum = 100;

  if (minimumBound < absoluteMinimum) return false;
  if (maximumBound > absoluteMaximum) return false;

  let min = Math.min(...grades);
  let max = Math.max(...grades);

  if (useAverage) {
    return checkAverageInBounds(minimumBound, maximumBound, grades); 
  }

  return checkAllGradesInBounds(minimumBound, maximumBound, grades); 
}

function calculateAverage(grades) {
  return grades.reduce((acc, curr) => acc + curr, 0)/grades.length;
}

function checkAverageInBounds(
  minimumBound,
  maximumBound,
  grades
){ 
  var avg = calculateAverage(grades);
  if (avg < minimumBound) return false;
  if (avg > maximumBound) return false;
  return true;
}

function checkAllGradesInBounds(
  minimumBound,
  maximumBound,
  grades
){ 
  var min = Math.min(...grades);
  var max = Math.max(...grades);

  if (min < minimumBound) return false;
  if (max > maximumBound) return false;
  return true;
}

function checkValid(
  minimum,
  maximum,
  grades,
  useAverage = false
){

  // Valid assignments should never allow fewer than 0 points
  var absoluteMinimum = 0;

  // Valid assignments should never exceed more than 100 possible points
  var absoluteMaximum = 100;

  if (minimumBound < absoluteMinimum) return false;
  if (maximumBound > absoluteMaximum) return false;

  let min = Math.min(...grades);
  let max = Math.max(...grades);

  if (useAverage) {
    return checkAverageInBounds(minimumBound, maximumBound, grades); 
  }

  return checkAllGradesInBounds(minimumBound, maximumBound, grades); 
}

function calculateAverage(grades) {
  return grades.reduce((acc, curr) => acc + curr, 0)/grades.length;
}

function checkAverageInBounds(
  minimumBound,
  maximumBound,
  grades
){ 
  var avg = calculateAverage(grades);
  if (avg < minimumBound) return false;
  if (avg > maximumBound) return false;
  return true;
}

function checkAllGradesInBounds(
  minimumBound,
  maximumBound,
  grades
){ 
  var min = Math.min(...grades);
  var max = Math.max(...grades);

  if (min < minimumBound) return false;
  if (max > maximumBound) return false;
  return true;
}

提取逻辑来确定成绩的平均值是否在其自身函数的最小值和最大值范围内。

Extract logic to determine whether the average of the grades is within minimum and maximum bounds in its own function.

提取逻辑来确定单独的函数中所有等级是否都在最小和最大范围内。

Extract logic to determine whether all the grades are within minimum and maximum bounds in a separate function.

好了！我们checkValid通过六个简单的步骤成功进行了重构。

Ta da! We’ve successfully refactored checkValid in six simple steps.

我们的新版本具有一些明显的好处。只需一眼，我们就能清楚地了解代码的目的是什么。我们还通过简化条件使其性能略有提高，并简化了容易出错的逻辑。总而言之，下一个开发人员更有可能能够轻松扩展此解决方案。这只是微观层面上的战略重构可能对您的应用程序产生的潜在积极影响的预览；现在想象一下它在大规模应用时可能产生的影响。

Our new version has some clear benefits. With just a glance, we can develop a solid sense of what the code aims to do. We’ve also made it the slightest bit more performant and simplified bug-prone logic by simplifying our conditions. All in all, the next developer is more likely to be able to extend on this solution without too much trouble. This is just a sneak peak into the potentially positive impact strategic refactoring at a microscopic level can have on your application; now imagine the impact that it can have when applied at scale.

但在我们坐下来开始认真重构之前，我们需要正确定位自己。我们需要了解我们想要改进的代码的历史，为此，我们需要了解代码是如何退化的。

But before we can sit down at our keyboards and start diligently refactoring, we need to orient ourselves properly. We need to understand the history of the code we want to improve, and for that, we need to understand how code degrades.

可扩展性

Scalability

我们经常尝试估计的一个要求是我们的产品需要扩展的方向和程度。这份要求清单可能相当冗长，并包含各种参数。例如，一个简单的 应用程序编程接口 (API) 请求，用于在系统中创建新的用户条目。我们可能会围绕请求的预期延迟、请求中执行的数据库查询数、每秒允许的新用户请求总数等设置一些指导方针。

One requirement we frequently attempt to estimate is the direction and degree to which our product needs to scale. This laundry list of requirements can get rather lengthy and include a wide range of parameters. Take, for instance, a simple application programming interface (API) request to create a new user entry in a system. We might set some guidelines around the expected latency of the request, the number of database queries executed within the request, the total number of new user requests allowed per second, and so on.

在推出新产品时，我们首先要考虑的是预计会有多少用户使用它。我们会设计一个我们认为可以轻松处理这个数字的解决方案（留出或留出安全误差范围）并发布它！如果我们的产品成功了，我们最终会拥有比我们最初预期多得多的用户，虽然从业务角度来看这当然是一个了不起的情况，但我们最初的实现可能无法处理这种新的、意料之外的负载。代码本身可能没有改变，但由于可扩展性要求的急剧变化，它实际上已经倒退了。

When launching a new product, one of our first assumptions deals with how many users we expect to use it. We craft a solution we think will comfortably handle that number (give or take a safe margin of error) and ship it! If our product is successful, we can end up with exponentially more users than we initially anticipated, and while that’s certainly an amazing situation to be in from a business perspective, our original implementation probably won’t be able to handle this new, unanticipated load. The code itself may not have changed, but it has effectively regressed due to a drastic shift in scalability requirements.

无障碍设施

Accessibility

每个应用程序都应从第一天起就努力做到尽可能地易于访问。我们应该使用适合色盲人士的配色方案，为图像和图标添加替代文本，并确保任何交互元素都可以通过键盘访问。不幸的是，急于发布新产品或新功能的团队往往会为了更积极的发布日期而掩盖可访问性。虽然发布新功能可能有助于您留住现有用户并吸引新用户，但如果这些功能无法供预期用户群的一部分使用，您就有疏远他们的风险。一旦您的产品变得无法供某些人使用，其感知效用就会大大降低。

Every application should strive to be as accessible as possible from day one. We should use color-blind-friendly color schemes, add alternative text for images and icons, and ensure that any interactive elements are accessible via the keyboard. Unfortunately, teams hastening to ship a new product or feature often gloss over accessibility in favor of a more aggressive launch date. While shipping new features might help you retain current users and attract new ones, if these features aren’t accessible to a subset of your anticipated user base, you risk alienating them. The second your product becomes inaccessible to some, its perceived utility substantially diminishes.

尽管自 1999 年以来，Web 无障碍倡议 (WAI) 仅针对官方的 Web 无障碍最佳实践进行了几次迭代，但许多重要的修订已经标准化。每次迭代时，活跃网站和应用程序的开发人员都必须重新审视有时长期未动过的代码，并实施任何必要的更改以符合最新标准。无障碍标准的迭代可能会降低应用程序的质量。

Although few iterations on official best practices for web accessibility have been developed by the Web Accessibility Initiative (WAI) since 1999, a number of important revisions have been standardized. With every new iteration, developers of active websites and applications must revisit code sometimes long untouched and implement any necessary changes to comply with the newest standards. Iterations on accessibility standards can decrease the quality of your application.

设备兼容性

Device Compatibility

每年，硬件公司都会发布新版本的设备；有时，他们甚至会更进一步，推出全新类型的设备。在智能手机、智能手表、智能汽车和智能电视中，我们一直在努力追赶，试图重新打包我们的应用程序，使其能够在最新硬件上无缝运行。用户已经逐渐期望他们最喜欢的应用程序可以在各种平台上运行。如果你是一款热门手机游戏的开发者，而一家大型硬件公司发布了一款具有更高屏幕分辨率的新设备，那么除非你发布专为处理更大屏幕而设计的新版游戏，否则你可能会失去很大一部分用户群。

Every year, hardware companies release new versions of their devices; sometimes, they’ll even take things a step further and introduce an entirely new class of device. Among smartphones, smart watches, smart cars, and smart TVs, we are constantly playing catch-up, attempting to repackage our applications to work seamlessly on the latest hardware. Users have grown to expect that their favorite applications work on a variety of platforms. If you’re a developer for a popular mobile game and a major hardware company releases a new device with a higher screen resolution, you risk losing a significant portion of your user base unless you ship a new version of your game built to handle the larger screen.

环境变化

Environmental Changes

当程序环境发生变化时，各种意想不到的行为都可能开始显现。在现代游戏电脑配备强大的图形处理能力 (GPU) 和数十 GB 的随机存取内存 (RAM) 之前，我们只能在街机游戏厅和客厅里使用简陋的小型游戏机。游戏开发者想出了巧妙的方法，利用有限的硬件来制作《太空侵略者》和《超级马里奥兄弟》等经典游戏。当时，使用中央处理器 (CPU) 时钟速度作为游戏中的计时器是标准做法。它提供了稳定可靠的时间测量。虽然这对于游戏机游戏来说不是问题，因为游戏卡带通常与更新、更强大的游戏机版本不兼容，但对于在个人电脑上运行的游戏来说，这却是一个相当严重的疏忽。随着新型计算机时钟速度的提高，游戏速度也随之提高。想象一下，必须以两倍于正常速度堆叠俄罗斯方块或躲避一连串的蘑菇怪；在某个时候，游戏变得完全无法使用。在这两个例子中，要求代码在特定的物理硬件上运行；不幸的是，硬件已经发生了巨大的变化，结果，代码质量下降了。

When changes occur in a program’s environment, all sorts of unexpected behavior can begin to manifest. Before the age of modern gaming computers loaded with powerful graphics processing limits (GPUs) and dozens of gigabytes of random-access memory (RAM), we had humble, little gaming consoles housed in arcades and, later, our living rooms. Game developers devised clever ways to use the limited hardware available to them to build classics like Space Invaders and Super Mario Bros. At the time, it was standard practice to use the central processing unit (CPU) clock speed as a timer in the game. It provided a steady, reliable measure of time. While this wasn’t a problem for console games, where the cartridges often weren’t compatible with newer, more powerful iterations of the console, it became a rather serious oversight for games running on personal computers. As clock speed on newer computers increased, so did the speed of gameplay. Imagine having to stack Tetris pieces or avoid a stream of Goombas at twice the normal speed; at a certain point, the game becomes wholly unusable. In both of these examples, the requirement was that the code was run on specific physical hardware; unfortunately, the hardware has since changed dramatically, and as a result, the code has degraded.

这类环境变化至今仍是一个严重问题。2018 年 1 月，Google Project Zero 和 Cyber​​us Technology 的安全研究人员与格拉茨技术大学的团队合作，发现了两个严重的安全漏洞，影响所有 Intel x86 微处理器、IBM POWER 处理器和一些基于高级 RISC 机器 (ARM) 的微处理器。第一个漏洞 Meltdown 允许恶意进程读取机器上的所有内存，即使在未经授权的情况下也是如此。第二个漏洞 Spectre 允许攻击者利用分支预测（受影响处理器的一项性能功能）来泄露有关机器上运行的其他进程的私人数据。您可以在官方网站上阅读有关这些漏洞及其内部工作原理的更多信息。

These types of environmental changes are still a serious concern today. In January 2018, security researchers from Google Project Zero and Cyberus Technology, in collaboration with a team at the Graz University of Technology, identified two serious security vulnerabilities affecting all Intel x86 microprocessors, IBM POWER processors, and some Advanced RISC Machine (ARM)-based microprocessors. The first, Meltdown, allowed rogue processes to read all memory on a machine, even when unauthorized to do so. The second, Spectre, allowed attackers to exploit branch prediction (a performance feature of the affected processors) to reveal private data about other processes running on the machine. You can read more about these vulnerabilities and their inner workings on the official website.

在漏洞披露时，所有运行 iOS、Linux、macOS 和 Windows （非最新版本）的设备都受到了影响。许多服务器和云服务以及大多数智能设备和嵌入式设备都受到了影响。几天之内，针对这两个漏洞的软件解决方案就出现了，但这些解决方案的性能损失为 5% 到 30%，具体取决于工作负载。英特尔后来报告称，它正在努力寻找方法，以帮助在下一代处理器中防范 Meltown 和 Spectre。即使是我们认为最稳定的东西（操作系统、固件）也容易受到其自身环境变化的影响；当我们在其上运行无数应用程序的这些核心底层系统受到影响时，我们反过来也会受到影响。

At the time of the disclosure, all devices running any but the most recent versions of iOS, Linux, macOS, and Windows were affected. A number of servers and cloud services were affected, as well as the majority of smart devices and embedded devices. Within days, software workarounds became available for both vulnerabilities, but these came at a performance cost of 5 to 30 percent, depending on the workload. Intel later reported it was working to find ways to help protect against both Meltown and Spectre in its next lineup of processors. Even the things we believe to be most stable (operating systems, firmware) are susceptible to changes in their own environments; and when these core, underlying systems on top of which we run countless applications are affected, we, in turn, are affected.

外部依赖项

External Dependencies

每个软件都有外部依赖关系；仅举几个例子，这些依赖关系可以是一组库、一种编程语言、一个解释器或一个操作系统。这些依赖关系与软件的耦合程度可能有所不同。这种依赖关系并不是什么新鲜事；人工智能研究早期的许多有影响力的程序都是用 Lisp 和类似 Lisp 的研究编程语言开发的，因为它们在 20 世纪 60 年代和 70 年代初得到了积极的开发。SHRDLU 是一个早期的自然语言理解计算机程序，它是在 PDP-6 上的 Micro Planner 中编写的，使用了如今已不复存在的非标准宏和软件库，因此遭受了无法修复的软件腐烂。

Every piece of software has external dependencies; to list just a few examples, these can be a set of libraries, a programming language, an interpreter, or an operating system. The degree to which these dependencies are coupled to the software can vary. This reliance isn’t anything new; many influential programs from the early days of artificial intelligence research were developed in Lisp and Lisp-like research programming languages as they were actively developed in the 1960s and early 1970s. SHRDLU, an early natural language–understanding computer program, was written in Micro Planner on a PDP-6, using nonstandard macros and software libraries that no longer exist today, thus suffering from irreparable software rot.

如今，我们尽最大努力更新外部依赖项，以便及时了解最新功能和安全补丁。然而，有时我们会降低更新优先级或忽略更新，尤其是对于我们未积极维护的代码。虽然允许依赖项落后几个版本可能不是眼前的问题，但确实存在风险。我们变得更容易受到安全漏洞的影响。我们还会在未来面临可能困难的升级体验。

Today, we do our best to update our external dependencies to keep up to date with the latest features and security patches. Sometimes, however, we either deprioritize or lose track of updates, especially when it comes to code we’re not actively maintaining. While allowing dependencies to fall a few versions behind might not be an immediate problem, it does come at a risk. We become more susceptible to security vulnerabilities. We also open ourselves up to potentially difficult upgrade experiences at a later date.

假设我们正在运行一个依赖于名为 Super Timezone Library 的开源库 1.8 版本的程序。在发布 4.0 版本仅几周后，Super Timezone Library 的开发人员宣布他们将不再积极支持 3.0 以下的任何版本。我们现在至少需要升级到 3.0 版本才能继续移植安全补丁。不幸的是，2.5 版本引入了一些向后不兼容的更改，而 2.8 版本弃用了我们应用程序中广泛使用的功能。过去几年来，保持库更新本来可能是一项小额的定期投资，但现在却变成了一项更为复杂、紧迫的投资。

Say we are running a program that relies on version 1.8 of an open-source library called Super Timezone Library. Just a few weeks after releasing version 4.0, the developers of Super Timezone Library announce that they will no longer actively support any versions below 3.0. We now need to upgrade to version 3.0 at the minimum to continue to port security patches. Unfortunately, version 2.5 introduced some backward-incompatible changes and version 2.8 deprecated functionality used widely in our application. What could have been a small, regular investment in keeping the library up to date over the past few years has now turned into a much more complex, urgent investment.

未使用的代码

Unused Code

需求变更可能会导致代码闲置。以一个面向公众的 API 为例。您的团队决定弃用该 API，并警告第三方开发人员即将进行的变更。不幸的是，在您传达了预期的变更、从网站上删除了文档并确保没有外部系统仍依赖该端点后，您的团队忘记删除代码。几个月后，一位新工程师开始实现一项新功能，偶然发现了已退役的 API 端点，并很自然地认为它仍然可以使用。他们决定将其重新用于自己的用例。不幸的是，他们很快发现代码并没有完全按照他们的意图运行，这仅仅是因为 API 被遗忘了，没有适应其余代码库和无数次需求变更的迭代。

Changes in requirements can lead to unused code. Take, for example, a publicly facing API. Your team decides to deprecate the API and warn third-party developers of the upcoming change. Unfortunately, after you’ve communicated the intended change, removed the documentation from your website, and ensured that no external systems were still relying on the endpoint, your team forgets to remove the code. A few months later, a new engineer begins implementing a new feature, stumbles upon the decommissioned API endpoint, and assumes, quite naturally, that it is still functional. They decide to repurpose it for their own use case. Unfortunately, they quickly find out that the code doesn’t do quite what they intended, simply because the API had been left in the dust and hadn’t adapted with the rest of the codebase and numerous iterations of requirement changes.

从开发人员的生产力角度来看，未使用的代码也会带来问题。每次遇到我们认为未使用的代码时，我们都必须非常小心地确定是否可以安全地删除它。除非我们配备了可靠的工具来帮助我们正确地突出显示死代码的范围，否则我们可能很难确定其确切的边界。如果我们不确定是否可以删除它，通常我们会继续前进，并希望其他人以后能弄清楚。谁知道有多少工程师在最终删除它之前会遇到同一段代码并问自己同样的问题！

Unused code can also be problematic from a developer productivity perspective. Every time we encounter code we believe to be unused, we have to determine very carefully whether we can safely remove it. Unless we’re equipped with reliable tooling to help us properly highlight the extent of the dead code, we might have a difficult time pinpointing its exact boundaries. If we aren’t sure whether we can delete it, usually we’ll just move on and hope someone else can figure it out later on. Who knows how many engineers will come across the same piece of code and ask themselves the same question before it’s finally removed!

最后，如果允许未使用的代码堆积起来，可能会影响性能。例如，如果您的团队负责网站的面向客户端部分，则浏览器请求的 JavaScript 文件的大小将直接影响初始页面加载时间。通常，文件越大，响应越慢。贪婪地请求臃肿的应用程序代码可能会对用户体验造成很大损害。

Finally, unused code, if allowed to pile up, can be a hindrance to performance. If, for example, your team works on the client-facing portion of a website, the size of the files the JavaScript files requested by your browser directly translates to initial page load times. Typically, the larger the file, the slower the response. Greedily requesting bloated application code can be quite detrimental to the user experience.

产品要求的变化

Changes in Product Requirements

大多数情况下，为今天或明天的产品需求编写解决方案，解决我们了解并能轻松预见的问题和限制，比为明年编写解决方案，试图解决未知的未来陷阱更容易。我们试图务实，权衡当前问题与未来问题，并试图确定我们应该投入多少时间来解决其中任何一个问题。有时，我们只是对未来没有很好的直觉。

Most of the time, it’s easier to write a solution for today or tomorrow’s product requirements, solving for the problems and constraints we understand and can easily anticipate, than to write one for next year, attempting to solve for unknown future pitfalls. We try to be pragmatic, weighing current concerns against future concerns, and attempting to determine how much time we should invest in solving for either. Sometimes, we simply don’t have a good intuition about the future.

函数的布尔参数是一个很好的例子，说明了预测未来产品需求的难度。大多数情况下，布尔参数被引入到现有函数中以修改其行为。（我们在“我们的第一个重构示例”中看到一个，其中布尔标志用于决定我们是否想知道每个成绩或这些成绩的平均值是否在给定的范围内。）当你找到一个函数几乎完全按照你的要求执行操作（只有一点例外）时，添加布尔标志通常是你可以做的最小、最简单的更改。不幸的是，这种类型的更改可能会导致各种各样的问题。我们可以在示例 2-1中看到其中一些问题，其中我们有一个小函数负责上传图像，给定一个文件名和一个表示该文件是否是 PNG 的标志。

Boolean arguments to functions are a great example of the difficulty of predicting future product requirements in action. Most of the time, Boolean arguments are introduced to existing functions to modify their behavior. (We saw one in “Our First Refactoring Example”, where a Boolean flag was used to decide whether we wanted to know whether each of the grades or the average of those grades fell in a given range.) Adding a Boolean flag is often the smallest, simplest change you can make when you find a function that does almost exactly what you want it to do, with just a tiny exception. Unfortunately, this type of change can cause all sorts of problems down the line. We can see some of those in action in Example 2-1, where we have a small function responsible for uploading an image given a filename and a flag denoting whether the file is a PNG.

function uploadImage(filename, isPNG) {
  // some implementation details
  if (isPNG) {
    // do some PNG-specific logic
  }
  // do some other things
}

function uploadImage(filename, isPNG) {
  // some implementation details
  if (isPNG) {
    // do some PNG-specific logic
  }
  // do some other things
}

如果几个月后我们决定支持一种新的图像格式，该怎么办？我们可能会决定向 designate 添加另一个布尔参数，如示例 2-2isGIF所示。

What if, a few months from now, we decide to support a new image format? We might decide to add another Boolean argument to designate isGIF, as shown in Example 2-2.

function uploadImage(filename, isPNG, isGIF) { 
  // some implementation details
  if (isPNG) {
    // do some PNG-specific logic
  } else if (isGIF) { 
    // do some GIF-specific logic
  }
  // do some other things
}

function uploadImage(filename, isPNG, isGIF) { 
  // some implementation details
  if (isPNG) {
    // do some PNG-specific logic
  } else if (isGIF) { 
    // do some GIF-specific logic
  }
  // do some other things
}

引入了一个新的布尔参数来指定图像是否是 GIF。

Introduced a new Boolean argument to designate whether the image is a GIF.

一张图片不能同时是 PNG 和 GIF，所以我们else if在这里添加了。

An image cannot be both a PNG and a GIF, so we’ve added an else if here.

要调用此函数并正确上传 GIF，我们需要记住将第二个布尔参数设置为 true。遇到调用的代码的读者uploadImage可能会感到困惑，需要参考函数定义来了解这两个布尔参数的作用。

To call this function and correctly upload a GIF, we would need to remember to set the second Boolean argument to true. Readers who come across the code calling out to uploadImage would likely be confused and need to refer to the function definition to understand what role the two Boolean arguments play.

function changeProfilePicture(filename) {
  // some implementation details
  if (isAnimated) {
    uploadImage(filename, false, true); 
  } else {
    uploadImage(filename, true, false); 
  }
  // do some other things
}

function changeProfilePicture(filename) {
  // some implementation details
  if (isAnimated) {
    uploadImage(filename, false, true); 
  } else {
    uploadImage(filename, true, false); 
  }
  // do some other things
}

这里我们正在上传 GIF。

Here we are uploading a GIF.

否则，我们正在上传 PNG。

Otherwise, we are uploading a PNG.

uploadImage开发人员在阅读诸如 之类的函数时不仅难以理解其工作原理changeProfilePicture，而且如果将来引入更多图像格式，这种模式将难以持续。向 support 添加第一个布尔参数的开发人员isPNG主要关心的是今天的问题，而不是明天的问题。更好的方法是将逻辑拆分为不同的函数：uploadJPG、uploadPNG和，如示例 2-4uploadGIF所示。

Not only is it difficult for developers to understand how uploadImage works when reading through functions like changeProfilePicture, it’s an unsustainable pattern to continue to maintain if more image formats are introduced in the future. The developer who added the first Boolean argument to support isPNG was mostly concerned with today’s problems rather than those of tomorrow. A better approach would be to split up the logic into distinct functions: uploadJPG, uploadPNG, and uploadGIF, as shown in Example 2-4.

function uploadImagePreprocessing(filename) {
  // some implementation details
}

function uploadImagePostprocessing(filename) {
  // do some other things
}

function uploadJPG(filename) {
  uploadImagePreprocessing();
  // do JPG things
  uploadImagePostprocessing();
}

function uploadPNG(filename) {
  uploadImagePreprocessing();
  // do PNG things
  uploadImagePostprocessing();
}

function uploadGIF(filename) {
  uploadImagePreprocessing();
  // do GIF things
  uploadImagePostprocessing();
}

function uploadImagePreprocessing(filename) {
  // some implementation details
}

function uploadImagePostprocessing(filename) {
  // do some other things
}

function uploadJPG(filename) {
  uploadImagePreprocessing();
  // do JPG things
  uploadImagePostprocessing();
}

function uploadPNG(filename) {
  uploadImagePreprocessing();
  // do PNG things
  uploadImagePostprocessing();
}

function uploadGIF(filename) {
  uploadImagePreprocessing();
  // do GIF things
  uploadImagePostprocessing();
}

现在你可能想知道，isPNG如果我们可以稍后重构它，为什么添加布尔参数是一个严重的问题。为了uploadImage正确替换所有出现的 ，我们需要单独审核每个调用点，并将其替换为uploadJPG或uploadPNG，具体取决于布尔参数是否设置为true。由于这些更改是手动的但很平凡，我们进行错误替换的可能性相当高，并可能导致一些严重的回归。根据问题的广泛程度以及它与其他关键业务逻辑的紧密耦合程度，重构看似简单的布尔参数可能是一项艰巨的任务。

Now you might be wondering why adding the isPNG Boolean argument is a serious problem if we can just refactor it later. To replace all occurrences of uploadImage properly, we’d need to audit each callsite individually and replace it with either uploadJPG or uploadPNG, depending on whether the Boolean argument is set to true. Because these changes are manual but mundane, the likelihood of us making the wrong replacement is quite high and could lead to some serious regressions. Depending on how widespread the problem might be, and how tightly coupled it might be to other crucial business logic, refactoring what seems like a simple Boolean argument might be a daunting task.

解决技术选择问题

Working Around Technology Choices

在实施新事物时，我们必须就使用哪些技术做出一些关键决定。我们必须选择一种语言、一个依赖项管理器、一个数据库等等。在应用程序可供任何用户使用之前，需要做出一长串决定。许多决定都是根据工程师的经验做出的；如果这些工程师更习惯使用一种技术而不是另一种技术，那么他们将比决定采用新堆栈更容易快速启动和运行项目。

When implementing something new, we have to make some critical decisions about which technologies we want to use. We have to choose a language, a dependency manager, a database, and so on. There’s a fairly long laundry list of decisions to make well before the application becomes available to any users. Many of these decisions are made given the engineers’ experience; if these engineers are more comfortable using one technology over another, they’ll have an easier time getting the project up and running quickly than if they decided to adopt a new stack.

一旦项目启动并取得一定进展，这些早期的技术决策就会受到考验。如果在应用程序的生命周期中，技术选择的问题出现得足够早，那么找到合适的替代方案并转向它可能会很容易且成本低廉，但这些选择的局限性往往在应用程序发展到这个阶段之后才会显现出来。

Once the project’s been launched and found some traction, these early technology decisions are put to the test. If a problem with a technology choice arises early enough in the lifetime of the application, it might be easy and inexpensive to find an appropriate alternative and pivot to it, but oftentimes the limitations of those choices don’t become apparent until well after the application has grown past this point.

其中一个决定可能是使用动态类型编程语言而不是静态类型编程语言来开发应用程序。 动态类型编程语言的支持者认为，它们使代码更易于阅读和理解；更少的严格定义的结构和类型声明的间接性使读者能够更好、更容易地理解代码的目的。许多人还吹嘘由于编译时间的减少，它们提供了更快的开发周期。

One such decision might be to develop an application by using a dynamically typed programming language instead of a statically typed programming language. Proponents of dynamically typed programming languages argue that they make the code easier to read and understand; less indirection around strictly defined structures and type declarations allow the reader to understand better and more readily the purpose of the code. Many also tout the quicker development cycle they provide due to the lack of compile time.

尽管使用动态类型编程语言有很多好处，但当应用程序超出临界规模时，它们就会变得难以管理。因为类型只在运行时进行验证，所以开发人员有责任通过编写一整套单元测试来确保类型的正确性，这些测试包括执行所有执行路径并断言预期的行为。如果变量名不能立即表明它可能属于哪种类型，那么新开发人员在熟悉不同结构如何相互作用时可能会遇到困难。最终需要进行防御性编程的情况并不少见，如示例 2-5所示，我们断言传递给函数的值具有某些属性并且不是无意的null。

While there are many upsides to using dynamically typed programming languages, they become difficult to manage when applications grow beyond a critical mass. Because types are only verified at runtime, it is the developer’s responsibility to ensure type correctness by writing a full suite of unit tests that exercises all execution paths and asserts expected behavior. New developers seeking to familiarize themselves with how different structures interact with one another might have a difficult time doing so if variable names do not immediately indicate which type it might be. It’s not uncommon to end up needing to program defensively, as shown in Example 2-5, where we assert that a value passed into a function has certain properties and isn’t unintentionally null.

function addUserToGroup(group, user) {

  if (!user) {
    throw 'user cannot be null';
  }

  // assert required fields
  if (!user.name) {
    throw 'name required';
  }

  if (!user.email) {
    throw 'email required';
  }

  if (!user.dateCreated) {
    throw 'date created required';
  }

  // assert no empty strings or other invalid values
  if (user.name === "") {
    throw 'name cannot be empty';
  }
  if (user.email === "") {
    throw 'email cannot be empty';
  }
  if (user.dateCreated === 0) {
    throw 'date created cannot be 0';
  }

  group.push(user);
  return group;
}

function addUserToGroup(group, user) {

  if (!user) {
    throw 'user cannot be null';
  }

  // assert required fields
  if (!user.name) {
    throw 'name required';
  }

  if (!user.email) {
    throw 'email required';
  }

  if (!user.dateCreated) {
    throw 'date created required';
  }

  // assert no empty strings or other invalid values
  if (user.name === "") {
    throw 'name cannot be empty';
  }
  if (user.email === "") {
    throw 'email cannot be empty';
  }
  if (user.dateCreated === 0) {
    throw 'date created cannot be 0';
  }

  group.push(user);
  return group;
}

由于 JavaScript 的动态特性，代码示例的作者很可能经常遇到无效用户在运行时通过调用堆栈的问题。作者只是想确保他们只将有效用户添加到组中，这完全可以理解。不幸的是，现在addUserToGroup主要关注的是确保提供的用户是有效的，而不是将用户添加到组中。随着对什么是有效的做出越来越多的决定user，整个代码库中的每个临时验证都需要更新。我们也有可能因为忘记更新这样一个位置而引入错误，这种情况的可能性也越来越大。最终，我们到处都会得到冗长、复杂、容易出错的函数。

It’s very likely the author of the code sample runs into issues regularly with invalid users weaving their way through a callstack at runtime simply due to the dynamic nature of JavaScript. The author just wants to be certain that they are only adding valid users to the group, and that’s completely understandable. Unfortunately, now addUserToGroup is primarily concerned with ensuring that the user provided is valid, rather than adding the user to the group. As more decisions are made about what constitutes a valid user, each of these ad hoc validations sprinkled throughout the codebase needs to be updated. There’s also an increasing chance we might introduce a bug by simply forgetting to update one such location. Eventually, we end up with lengthy, convoluted, bug-prone functions everywhere.

我们可以引入一个新函数来帮助缓解代码质量下降。假设我们编写了一个简单的帮助程序来封装验证user对象的所有逻辑；我们将其称为validateUser。示例 2-6展示了其实现。

We can introduce a new function to help mitigate code degradation. Let’s say we write up a simple helper to encapsulate all the logic for validating a user object; we’ll call it validateUser. Example 2-6 shows its implementation.

function validateUser(user) {
  if (!user) {
    throw 'user cannot be null';
  }

  // assert required fields
  if (!user.name) {
    throw 'name required';
  }

  if (!user.email) {
    throw 'email required';
  }

  if (!user.dateCreated) {
    throw 'date created required';
  }

  // assert no empty strings or other invalid values
  if (user.name === "") {
    throw 'name cannot be empty';
  }
  if (user.email === "") {
    throw 'email cannot be empty';
  }
  if (user.dateCreated === 0) {
    throw 'date created cannot be 0';
  }

  return;
}

function validateUser(user) {
  if (!user) {
    throw 'user cannot be null';
  }

  // assert required fields
  if (!user.name) {
    throw 'name required';
  }

  if (!user.email) {
    throw 'email required';
  }

  if (!user.dateCreated) {
    throw 'date created required';
  }

  // assert no empty strings or other invalid values
  if (user.name === "") {
    throw 'name cannot be empty';
  }
  if (user.email === "") {
    throw 'email cannot be empty';
  }
  if (user.dateCreated === 0) {
    throw 'date created cannot be 0';
  }

  return;
}

然后我们可以更新addUserToGroup以使用我们的新辅助函数，大大简化逻辑，如示例 2-7所示。

We can then update addUserToGroup to use our new helper function, drastically simplifying the logic, as shown in Example 2-7.

function addUserToGroup(group, user) {
  validateUser(user);
  group.push(user);
  return group;
}

function addUserToGroup(group, user) {
  validateUser(user);
  group.push(user);
  return group;
}

不幸的是，虽然调用 对我们来说要容易得多validateUser，但替换我们之前枚举每个检查的所有位置将是一项简单的任务。首先，我们必须识别每个位置。如果我们处理大型代码库，这可能是一项艰巨的任务。其次，在审核每个位置时，我们可能会发现一些我们忘记了一两个检查的情况。在某些情况下，这是一个错误，我们可以通过一次调用 安全地替换检查validateUser；在其他情况下，这可能是故意的，我们不能盲目地用我们的新助手替换现有代码，否则可能会引入回归。因此，减轻防御性编程的负担需要我们计划和执行大规模重构。

Unfortunately, while it’s much easier for us to call validateUser, replacing all the locations where we previously enumerated each check will be an easy task. First, we have to identify each of those spots. If we’re dealing with a large codebase, that might be a daunting task. Second, in auditing each of these locations, we’ll probably end up finding a handful of instances where we’ve forgotten a check or two. In some cases, this is a bug, and we can safely replace the checks with a single call to validateUser; in other cases, this might have been intentional, and we cannot blindly replace the existing code with our new helper at the risk of introducing a regression. As such, easing the burden of our defensive programming requires us to plan and execute a sizable refactor.

持续缺乏组织

Persistent Lack of Organization

维护有序的代码库有点像保持家里整洁。似乎总有比收拾堆在梳妆台上的衣服或整理咖啡桌上堆积的邮件更重要的事情要做。但我们积累的东西越多，当我们终于有时间整理时，我们花在梳理上的时间就越多。你甚至可能会让杂物堆积到开始溢出到其他表面的地步。当我的父母鼓励我保持整洁并每天打扫一点时，他们知道这是有道理的；他们知道处理小混乱总是比处理大混乱容易得多。

Maintaining an organized codebase is a little bit like maintaining a tidy home. It seems as though there’s always something more important to do than to put away the clothes heaped over the dresser or sort through the stack of mail accumulating on the coffee table. But the more we accumulate, the more time we’ll spend combing through it all when we finally get around to it. You might even allow the clutter to build up to the point that it’s begun overflowing on to other surfaces. My parents were onto something when they encouraged me to keep things tidy and clean up just a little bit every day; they knew that it was always much easier to take care of a small mess than a massive one.

在保持代码库井然有序方面，我们中的许多人都陷入了相同的模式。例如，一个文件结构相对扁平的代码库。大多数代码被组织成二十几个文件，只有一个目录用于测试。应用程序以稳定的速度增长，每月都会添加一些新文件。因为维持现状更容易，工程师们没有主动开始将相关文件组织到目录中，而是学会了浏览日益杂乱的代码。新工程师被引入到日益混乱的环境中，发出警告，鼓励团队开始拆分代码，但这些担忧没有被理会；经理们鼓励他们专注于迫在眉睫的最后期限，资深工程师耸耸肩，向他们保证，他们很快就会找到如何在混乱中提高生产力。最终，代码库达到了临界点，持续的组织不力大大降低了整个工程团队的生产力。只有这样，团队才会花时间起草一个整理代码库的计划，此时需要考虑的变量数量将远远超过他们几个月（甚至几年）前齐心协力解决问题的数量。

Many of us fall into the same patterns when it comes to keeping our codebases organized. Take, for instance, a codebase with a relatively flat file structure. Most of the code is organized into two dozen or so files, with a single directory for tests. The application grows at a steady pace, with a few new files added every month. Because it’s easier to maintain the status quo, instead of proactively beginning to organize related files into directories, engineers instead learn to navigate the increasingly sprawling code. New engineers introduced to the growing chaos raise a warning flag and encourage the team to begin splitting up the code, but these concerns fall on deaf ears; managers encourage them to focus on the deadlines looming ahead, and tenured engineers shrug and reassure them that they’ll quickly figure out how to be productive in the disarray. Eventually, the codebase reaches a critical mass in which the persistent lack of organization has dramatically slowed productivity across the engineering team. Only then does the team take the time to draft a plan for grooming the codebase, at which point the number of variables to consider is far greater than it would have been, had they made a concerted effort to tackle the problem months (or even years) earlier.

行动太快

Moving Too Quickly

如果不加以控制，快速迭代和产品开发会迅速降低软件质量。在紧迫的期限内开发新产品功能时，我们往往会偷工减料：我们会省略一些测试用例，给变量起通用名称，或者在本来if可以创建新函数的地方添加一些语句。如果我们没有在达到目标期限后立即正确记录偷工减料的情况并分配必要的时间来纠正它们，它们就会堆积起来。很快，您就会得到非常冗长的函数，其中充斥着分支逻辑，并且整个代码库中几乎没有单元测试覆盖率。在更复杂的应用程序中，多个团队同时迭代不同的功能，行动过快的影响开始累积。除非每个团队都能有效地与其他团队沟通产品变化，否则垃圾会堆积起来。您可以在图 2-1中看到这种复合效应的示例。

Rapid iteration and product development can swiftly degrade software quality if not kept in check. When building out new product features under aggressive deadlines, we tend to cut corners: we’ll omit a few test cases, give variables generic names, or add a few if statements where we could have made a new function. If we do not properly make note of the corners we’ve cut and allocate the time necessary to correct them immediately after we’ve met our target deadline, they pile up. Soon, you end up with exceedingly lengthy functions, littered with branching logic and little-to-no unit test coverage sprinkled throughout your codebase. When working in more complex applications, where multiple teams are iterating on distinct features alongside one another, effects of moving too quickly begin to compound. Unless every team can communicate product changes effectively with every other team, the amount of cruft piles up. You can see an example of that compounding effect illustrated in Figure 2-1.

我们许多从事现代应用程序开发的人都实践持续集成和交付；我们尽可能频繁地将更改合并回主分支，在那里通过对应用程序的新版本运行自动测试来验证这些更改。我们通过将这些更改置于功能标志（也称为功能切换）后面来确保客户不会接触到半生不熟的功能和部分错误修复。虽然这些功能在积极开发期间为我们提供了很大的灵活性，但一旦我们成功地将更改引入所有用户，它们就很容易被遗忘。

Many of us working on modern applications practice continuous integration and delivery; we merge our changes back into the main branch as often as possible, where they’re validated by running automated tests against a new build of the application. We ensure that customers aren’t exposed to half-baked features and partial bug fixes by gating these changes behind feature flags (otherwise known as feature toggles). While these give us a good amount of flexibility during active development, they’re easy to forget about once we’ve successfully introduced the change to all the users.

图 2-1.随时间推移的垃圾积累图

我工作过的每家公司都有数十个（甚至数百个）功能标志，尽管这些标志已为整个生产启用，但仍在程序中被引用。虽然保留其中一些检查似乎没什么问题，但存在一些明显的风险。

Every company I’ve worked for had dozens (if not hundreds) of feature flags still being referenced in the program well after they’d been enabled for all of production. While it might seem benign to leave a few of these checks lying around, there are some distinct risks.

首先，这会给阅读代码的开发人员增加认知负担；如果开发人员不花时间验证功能的状态，他们可能会误以为该功能仍在积极开发中，并且只会在非门控代码路径中做出重要更改。其次，花时间确定该功能是否在生产中处于活动状态，却发现它已经向所有人开放了数周，这可能会令人沮丧。在严重的情况下，如果有数百个基本上失效的功能标志，这可能会对应用程序的性能产生非常严重的影响。验证给定请求或代码路径的每个与功能相关的条件所花费的累计时间可能非常长。通过清理过时的标志，我们可能都会看到一些性能增强。

First, it causes added cognitive load on developers reading the code; if the developer doesn’t take the time to verify the status of the feature, they might be misled into thinking it is still under active development and only make an important change in the nongated codepath. Second, it can be frustrating to spend time determining whether the feature is active in production, only to find out that it’s been live to everyone for weeks. In the severe cases where there are hundreds of essentially defunct feature flags, this can have a very serious performance impact on the application. The cumulative time spent validating each feature-related conditional for a given request or codepath can be significant. We might all see some performance enhancements by cleaning up our obsolete flags.

哈尔斯特德指标

Halstead Metrics

1975 年，莫里斯·哈尔斯特德 (Maurice Halstead) 首次提出通过计算给定计算机程序中的运算符和操作数的数量来衡量软件的复杂性。他认为，由于程序主要由这两个单元组成，因此计算它们的唯一实例可能为我们提供有关程序大小的有意义的度量，从而表明其复杂性。

Maurice Halstead first proposed measuring the complexity of software in 1975 by counting the number of operators and operands in a given computer program. He believed that because programs mainly consisted of these two units, counting their unique instances might give us a meaningful measure of the size of the program and therefore indicate something about its complexity.

运算符是一种行为类似于函数的结构，但在语法或语义上与典型函数不同。这些运算符包括算术符号（如-and +）、逻辑运算符（如&&）、比较运算符（如>）和赋值运算符（如=）。例如，举个例子，一个简单的函数将两个数字相加，如示例 3-1所示。

Operators are constructs that behave like functions, but differ syntactically or semantically from typical functions. These include arithmetic symbols like - and +, logical operators like &&, comparison operators like >, and assignment operators like =. Take, for instance, a simple function that adds two numbers together, as shown in Example 3-1.

function add(x, y) {
  return x+y;
}

function add(x, y) {
  return x+y;
}

它包含一个运算符，即加法运算符+。另一方面，操作数是我们使用一组运算符进行操作的任何实体。在我们的加法示例中，我们的操作数是x和y。

It contains a single operator, the addition operator, +. Operands, on the other hand, are any entities we operate on, using our set of operators. In our addition example, our operands are x and y.

鉴于这些简单的数据点，Halstead 提出了一组指标来计算一组特征：

Given these simple data points, Halstead proposed a set of metrics to calculate a set of characteristics:

1. 程序的容量，或者代码读者需要吸收多少信息才能理解其含义。

2. A program’s volume, or how much information the reader of the code has to absorb in order to understand its meaning.

3. 程序的难度，或者重新创建软件所需的脑力劳动量；也通常称为 Halstead 工作量指标。

4. A program’s difficulty, or the amount of mental effort required to re-create the software; also commonly referred to as the Halstead effort metric.

5. 您可能在系统中发现的错误数量。

6. The number of bugs you are likely to find in the system.

为了更好地说明 Halstead 的思想，我们可以将运算符和操作数计数技术应用到一个稍微复杂一些的函数上，该函数计算整数的素因数，如示例 3-2所示。我们在表 3-1中列举了每个唯一的运算符和操作数，以及它们在程序中出现的次数。

To illustrate Halstead’s ideas better, we can apply our operator and operand counting technique to a slightly more complicated function, which calculates an integer’s prime factors, as in Example 3-2. We’ve enumerated each of the unique operators and operands, along with the number of times they occur in the program, in Table 3-1.

function primeFactors(number) {
  function isPrime(number) {
    for (let i = 2; i <= Math.sqrt(number); i++) {
      if (number % i === 0) return false;
    }
    return true;
  }

  const result = [];
  for (let i = 2; i <= number; i++) {
    while (isPrime(i) && number % i === 0) {
      if (!result.includes(i)) result.push(i);
      number /= i;
    }
  }
  return result;
}

function primeFactors(number) {
  function isPrime(number) {
    for (let i = 2; i <= Math.sqrt(number); i++) {
      if (number % i === 0) return false;
    }
    return true;
  }

  const result = [];
  for (let i = 2; i <= number; i++) {
    while (isPrime(i) && number % i === 0) {
      if (!result.includes(i)) result.push(i);
      number /= i;
    }
  }
  return result;
}

鉴于我们的质因数分解程序有 18 个唯一运算符 (n1 ₎、14 个唯一操作数 (n2 ₎以及总操作数 37 (N2 ₎，我们可以使用 Halstead 难度测量法来计算与读取程序相关的相对难度，其基本方程为：

Given that our prime factorization program has 18 unique operators (n₁), 14 unique operands (n₂), and a total operand count of 37 (N₂), we can use Halstead’s difficulty measure to calculate the relative difficulty associated with reading the program with the basic equation:

代入我们的数值，我们得到总体难度分数为 23.78。

Substituting in our values, we obtain an overall difficulty score of 23.78.

虽然 23.78 本身可能意义不大，但通过处理代码的各个部分，我们可以逐渐了解该分数如何映射到我们的体验中。随着时间的推移，通过反复接触这些值及其实现，我们能够更好地解释 23.78 的分数在我们应用程序的更大背景下意味着什么。

Although 23.78 might not signify much on its own, we can gradually acquire an understanding of how this score maps to our experiences, working with individual sections of our code. Over time, through repeated exposure to these values alongside their implementations, we become better able to interpret what a score of 23.78 signifies within the greater context of our application.

圈复杂度

Cyclomatic Complexity

圈复杂度由 Thomas McCabe 于 1976 年开发，是对程序源代码中线性独立路径数量的定量度量。它本质上是对程序中控制流语句数量的计数。这包括if语句、while循环for和case侧switch块中的语句。

Developed by Thomas McCabe in 1976, cyclomatic complexity is a quantitative measure of the number of linearly independent paths through a program’s source code. It is essentially a count of the number of control flow statements within a program. This includes if statements, while and for loops, and case statements in side switch blocks.

以一个没有控制流组件的简单程序为例，如示例 3-3所示。为了计算其循环复杂度，我们首先为函数声明分配 1，并随着遇到的每个决策点递增。示例 3-3 的循环复杂度为 1，因为该函数只有一条路径。

Take, for example, a simple program with no control flow components, as shown in Example 3-3. To calculate its cyclomatic complexity, we first assign 1 for the function declaration, incrementing with every decision point we encounter. Example 3-3 has a cyclomatic complexity of 1 because there is only one path through the function.

function convertToFahrenheit(celsius) {
  return celsius * (9/5) + 32;
}

function convertToFahrenheit(celsius) {
  return celsius * (9/5) + 32;
}

让我们看一个更复杂的例子，比如示例 3-2primeFactors中的函数。在示例 3-4中，我们将其简化并枚举每个控制流点，以得出循环复杂度为 6。

Let’s look at a more complex example, like our primeFactors function from Example 3-2. In Example 3-4, we reduce it and enumerate each of the control flow points to yield a cyclomatic complexity of 6.

function primeFactors(number) { 
  function isPrime(number) {
    for (let i = 2; i <= Math.sqrt(number); i++) { 
      if (number % i === 0) return false; 
    }
    return true;
  }

  const result = [];
  for (let i = 2; i <= number; i++) { 
    while (isPrime(i) && number % i === 0) {
      if (!result.includes(i)) result.push(i); 
      number /= i;
    }
  }
  return result;
}

function primeFactors(number) { 
  function isPrime(number) {
    for (let i = 2; i <= Math.sqrt(number); i++) { 
      if (number % i === 0) return false; 
    }
    return true;
  }

  const result = [];
  for (let i = 2; i <= number; i++) { 
    while (isPrime(i) && number % i === 0) {
      if (!result.includes(i)) result.push(i); 
      number /= i;
    }
  }
  return result;
}

函数声明是第一个控制流点。

Function declaration is the first control flow point.

第一个for循环是我们的第二点。

First for loop is our second point.

第一条if陈述是我们的第三点。

First if statement is our third point.

第二个for循环是第四个点。

Second for loop is the fourth point.

while是第五点。

while is the fifth point.

第二if是第六点。

Second if is the sixth point.

当我们阅读一段代码时，每次出现分支（语句if、for循环等）时，我们都必须开始推理具有多条执行路径的多个状态。我们必须能够在头脑中保存更多信息才能理解代码的作用。因此，如果循环复杂度为 6，我们可以推断 primeFactors阅读和理解代码可能并不太难。

When we’re reading a chunk of code, every time there is a branch (an if statement, a for loop, etc.), we have to begin to reason about multiple states with multiple paths of execution. We have to be able to hold more information in our heads to understand what the code does. So, with a cyclomatic complexity of 6, we can infer that primeFactors is probably not too difficult to read and understand.

计算程序中的决策点数量是 McCabe 提出的计算程序复杂度方法的简化版。从数学上讲，我们可以通过生成表示程序控制流的有向图来计算结构化程序的圈复杂度；每个节点代表一个基本块（即没有分支的直线代码序列），如果有一种方法可以从一个块传递到另一个块，则有一条边将它们连接起来。给定此图，其复杂度M定义如下式，其中E是边的数量，N是节点的数量，P是连接组件的数量，其中连接组件是所有节点都可以彼此到达的子图。

Counting the number of decision points in a program is a simplification of McCabe’s proposed method of calculating its complexity. Mathematically, we can calculate the cyclomatic complexity of a structured program by generating a directed graph representing its control flow; each node represents a basic block (i.e., a straight-line code sequence with no branches), with an edge linking them if there is a way to pass from one block to the other. Given this graph, its complexity, M, is defined as in the following equation, where E is the number of edges, N is the number of nodes, and P is the number of connection components, where a connected component is a subgraph where the nodes are all reachable from one another.

图 3-1显示了 的一个示例控制流primeFactors。

Figure 3-1 shows an example control flow for primeFactors.

图 3-1。的控制流图primeFactors，蓝色节点表示非终止状态，红色节点表示终止状态。在这个例子中，我们有 13 条边、11 个节点和 2 个连通分量。

NPath 复杂度

NPath Complexity

NPath 复杂度是 Brian Nejmeh 于 1988 年提出的，作为现有复杂度指标的替代方案。他认为，专注于非循环执行路径并不能充分模拟路径的有限子集与所有可能执行路径集之间的关系。我们可以从循环复杂度不考虑控制流结构的嵌套这一事实中观察到这一限制。for连续三个循环的函数将产生与三个嵌套循环相同的度量for。嵌套会影响函数的心理复杂性，而心理复杂性会对我们维护软件质量的能力产生很大影响。

NPath complexity was proposed as an alternative to existing complexity metrics in 1988 by Brian Nejmeh. He argues that focusing on acyclic execution paths did not adequately model the relationship between finite subsets of paths and the set of all possible execution paths. We can observe this limitation in the fact that cyclomatic complexity does not consider nesting of control flow structures. A function with three for loops in succession will yield the same metric as one with three nested for loops. Nesting can influence the psychological complexity of the function, and psychological complexity can have a large impact on our ability to maintain software quality.

McCabe 的度量可能很容易计算，但它无法区分不同类型的控制流结构，将if语句while与for循环等同对待。Nejmeh 断言并非所有控制流结构都是相同的；有些控制流结构比其他结构更难理解和正确使用。例如，while对于开发人员来说，循环可能比语句更难推理switch。NPath 复杂度试图解决这个问题。不幸的是，这使得计算起来有点困难，即使对于小程序也是如此，因为计算是递归的，并且很快就会膨胀。我们将通过几个带有语句的示例来介绍计算方法，if以熟悉其工作原理。如果您想更好地了解如何计算 NPath 复杂度，给定更大范围的控制流语句（包括嵌套控制流），我强烈建议您阅读 Nejmeh 的论文。

McCabe’s metric might be easy to calculate, but it fails to distinguish between different kinds of control flow structures, treating if statements identically to while or for loops. Nejmeh asserts that not all control flow structures are equal; some are more difficult to understand use properly than others. For example, a while loop might be trickier for a developer to reason about than a switch statement. NPath complexity attempts to address this concern. Unfortunately, this makes it a bit more difficult to calculate, even for small programs, because the calculation is recursive and can quickly balloon. We’ll walk through the calculations for a few examples with if statements to get familiar with how it works. If you’d like to gain a better understanding of how to calculate NPath complexity, given a greater range of control flow statements (including nested control flows), I highly recommend reading Nejmeh’s paper.

NPath 复杂度的基本情况与示例 3-3中先前的温度转换函数相同；对于没有决策点的简单程序，NPath 复杂度为 1。为了说明度量的乘法成分，我们将看一个具有几个嵌套条件的简单函数if。

Our base case for NPath complexity is the same as for our previous temperature converter function in Example 3-3; for a simple program with no decision points, the NPath complexity is 1. To illustrate the multiplicative component of the metric, we’ll take a look at a simple function with a few nested if conditions.

示例 3-5展示了一个简短的函数，该函数在给定速度的情况下返回收到超速罚单的可能性。阅读该函数，我们到达第一条if语句，此时给定的速度可以小于或大于 45 公里/小时。然后有两种可能的路径：如果速度大于 45 公里/小时，我们将代码输入if块中；如果不是，我们只需继续。接下来我们需要验证速度是否比提供的速度限制高出 10 公里/小时，此时我们再次通过代码获得两种可能路径。最终，我们返回计算出的风险因子。

Example 3-5 shows a short function that returns the likelihood of receiving a speeding ticket, given a provided speed. Reading through the function, we reach a first if statement, at which point the given speed can either be less than or greater than 45 km/h. There are then two possible paths: if the speed is greater than 45 km/h, we enter the code inside the if block; if not, we simply continue. We next need to verify whether the speed is greater than 10 km/h over the supplied speed limit, at which point we again have two possible paths through the code. Eventually, we return our calculated risk factor.

function likelihoodOfSpeedingTicket(currentSpeed, limit){
  risk = 0;  // A

  if (currentSpeed < 45) {
    risk = 1; // B
  } // C

  if (currentSpeed > (limit + 10)) {
    risk = 2; // D
  } // E

  return risk; // F
}

function likelihoodOfSpeedingTicket(currentSpeed, limit){
  risk = 0;  // A

  if (currentSpeed < 45) {
    risk = 1; // B
  } // C

  if (currentSpeed > (limit + 10)) {
    risk = 2; // D
  } // E

  return risk; // F
}

NPath 复杂度计算函数中不同路径的数量。我们可以通过使用一系列值进行调用来枚举每条路径，并执行每组条件。我们将一起遍历一个输入，突出显示我们遍历函数的路径。所有其他唯一路径均在表 3-2likelihoodOfSpeedingTicket中进行了标记。

NPath complexity calculates the number of distinct paths through a function. We can enumerate each of these paths by calling likelihoodOfSpeedingTicket with a range of values, exercising each set of conditions. We’ll walk through one input together, highlighting the path we traverse through the function. All other unique paths are labeled in Table 3-2.

假设我们likelihoodOfSpeedingTicket用currentSpeedof30和limitof调用0。第一个if语句的计算结果为true，从而得出 B。第二个if语句的计算结果也为 true ，从而得出 D。然后我们在 F 处到达 return 语句。对各种输入重复此模式，我们确定该函数有四条唯一路径。因此，我们的 NPath 分数为 4。

Say we call likelihoodOfSpeedingTicket with a currentSpeed of 30 and limit of 0. Our first if statement will evaluate to true, leading us to B. Our second if statement will also evaluate to true, leading us to D. Then we reach our return statement at F. Repeating this pattern for a variety of inputs, we determine that there are four unique paths through the function. Therefore, our NPath score is 4.

代码行数

Lines of Code

不幸的是，控制流图指标可能很难（有时成本高昂）计算，特别是对于非常大的代码库（这正是我们希望改进的代码库）。这就是程序大小发挥作用的地方。虽然它可能不像 Halstead、McCabe 或 Nejmeh 的算法那么科学，但结合其他测量方法，程序大小可以帮助我们找到应用程序中可能的痛点。如果我们正在寻找一种务实、省力的方法来量化代码的复杂性，那么基于大小的指标就是最佳选择。

Unfortunately, control flow graph metrics can be difficult (and sometimes expensive) to calculate, particularly for very large codebases (which are precisely the ones we’re looking to improve). This is where program size comes into play. Although it may not be quite as scientific as Halstead, McCabe, or Nejmeh’s algorithms, combined with other measurements, program size can help us locate likely pain points in our application. If we’re looking for a pragmatic, low-effort approach to quantifying the complexity of our code, then size-based metrics are the way to go.

在测量代码长度时，我们有几个可用的选项。大多数开发人员选择仅测量逻辑代码行，完全忽略空行和注释。与控制流指标一样，我们可以在多种分辨率下收集此信息。我发现以下几个数据点是非常有用的参考点：

When measuring code length, we have a few options available to us. Most developers choose to measure only logical lines of code, omitting empty lines and comments entirely. As with our control flow metrics, we can collect this information at a number of resolutions. I’ve found the following few data points to be quite helpful reference points:

每个文件的代码行数 (LOC)

LOC (lines of code) per file

每个代码库都有这样一种文件，如果你从头开始滚动，似乎可能无法到达末尾。测量这些文件的代码行数可能会准确地反映出当开发人员在编辑器中打开它们时了解其内容和职责所需的心理负担。

Every codebase has the kind of files that look as if you might not reach the end if you started scrolling from the beginning. Measuring the number of lines of code for these would likely accurately capture the psychological overhead required to understand their contents and responsibilities when a developer pops them open in their editor.

函数长度

Function length

对于每个无限文件，都有一个无限函数。（通常情况下，无限函数存在于无限文件中。）测量应用程序中函数或方法的长度可以成为一种估算其各自复杂性的有效方法。

For every endless file, there’s an endless function. (More often than not, the endless functions are found in the endless files.) Measuring the length of functions or methods within your application can be a helpful way of approximating their individual complexities.

每个文件、模块或类的平均函数长度

Average function length per file, module, or class

根据应用程序的组织方式，您可能需要跟踪每个逻辑单元的平均函数或方法长度。在面向对象的代码库中，您可能希望跟踪类或包中每个方法的平均长度。在命令式代码库中，您可以测量文件或较大模块中每个函数的平均长度。无论组织单元有多大，了解其中包含的较小逻辑组件的平均长度都可以让您了解整个单元的相对复杂程度。

Depending on how your application is organized, you may want to keep track of the average function or method length per logical unit. In object-oriented codebases, you likely want to keep track of the average length of each method within a class or package. In an imperative codebase, you might measure the average length of each function within a file or larger module. Whatever the greater organizational unit, knowing the average length of the smaller logical components contained within it can give you an indication of the relative complexity of that unit as a whole.

LOC 可能会有很大差异，具体取决于程序语言或编程风格，但如果我们在比较同类事物，就不应该太担心。在大规模重构时，我们通常关注的是改进单个大型代码库中的代码。根据我的经验，绝大多数使用这些代码库的开发人员都已投入精力建立样式指南，定义一套最佳实践，并经常使用自动格式化程序来执行这些规则。不同团队和组件之间不可避免地会存在一些差异，但从广义上讲，整个应用程序往往看起来足够相似，因此来自代码库不同部分的两组 LOC 指标应该仍然可以比较。

LOC might vary wildly, depending on the language of a program or programming style, but if we’re comparing apples to apples, we shouldn’t be too concerned. When refactoring at scale, we’re generally concerned with improving code within a single, large codebase. In my experience, the vast majority of developers working with these codebases have invested in establishing style guides, defining a set of best practices, and often enforcing these rules with autoformatters. Some variation is inevitable across teams and components, but broadly speaking, the application as a whole tends to look similar enough that two sets of LOC metrics from distinct sections of the codebase should still be comparable.

正式文件

Formal Documentation

正式文档是您最有可能想到的所有内容。它不必遵循任何官方的行业级标准（例如统一建模语言 [UML]）。相反，正式文档的正式之处在于它是专门编写的（并且在许多情况下是积极维护的），以便向读者介绍您的系统。技术规格、架构图、风格指南、入门材料和事后总结都是正式文档的一些示例。

Formal documentation is everything you most likely think of as documentation. This doesn’t have to follow any official, industry-level standard (like Unified Modeling Language [UML]). Rather, what makes it formal is that it was deliberately authored (and, in many cases, is actively maintained) to inform the reader about your system. Technical specs, architecture diagrams, style guides, onboarding materials, and postmortems are a few examples of formal documentation.

我们可以使用技术规范之类的东西作为证据，证明我们的重构是必要或有用的，方法是引用设计决策、假设或其他考虑或拒绝的设计。例如，假设您正在处理应用程序的一个子部分，该子部分负责处理产品中所有与用户相关的操作。当前的实现要求开发人员编写新功能来记住并枚举当用户修改其个人资料时需要触发并传播到同级子系统的每种事件。如果您的团队有为每项功能编写技术设计规范的历史，您可以找到事件传播的原始规范文档。本文档描述了当前的实现、其局限性以及任何替代方法。

We can use things like technical specs as evidence that our refactor is necessary or useful by referencing design decisions, assumptions, or other designs considered or rejected. Say, for instance, you work on a subsection of your application responsible for processing all user-related actions within your product. The current implementation requires developers writing new features to remember and enumerate every kind of event that needs to be fired and propagated to sibling subsystems when a user modifies their profile. If your team has a history of writing technical design specs for each of their features, you can locate the original specification document for event propagation. This document describes the current implementation, its limitations, and any alternative approaches.

限制部分指出，虽然在每个位置单独触发每个所需事件可能很方便，但如果团队引入大量新事件，这可能会变得笨拙和繁重。今天，您的系统正遇到同样的问题。它处理十几种事件类型，您的团队正在努力跟踪这种蔓延。对于每个新功能，您的团队都担心忘记触发关键事件类型并可能引入令人讨厌的错误。您已尽最大努力通过测试断言所需的行为，但决定重构这些事件的处理方式是驯服重复逻辑混乱的最佳解决方案。

The limitations section states that while it might be convenient to trigger each required event individually at every location, if the team introduces a substantial number of new events, it might become clumsy and burdensome. Today, your system is experiencing that exact problem. It handles more than a dozen event types and your team is struggling to keep track of the sprawl. With every new feature, your team fears forgetting to trigger a critical event type and potentially introducing a pesky bug. You’ve done your best to assert the desired behavior with tests but decide that refactoring how these events are handled is the best solution to taming the chaos of repetitive logic.

技术规格对于支持您的假设非常有用，可以准确地说明需要改进的内容和改进方法。有时，这些文档会概述考虑过但最终未采用的替代方法。您可以在重构工作中探索其中一种建议。

Technical specs can be very helpful in supporting your hypothesis of exactly what needs to be improved and how. Occasionally, these documents outline alternative approaches considered but not ultimately chosen. You may be able to explore one of these suggestions with your refactoring effort.

风格指南和入门材料的维护者有时会在他们编写的文档中留下他们经验的痕迹。如果他们最近意外发现了某些东西的工作原理，并试图根据这种经验改进文档，那么您可能会在他们的文章中看到一些蛛丝马迹。您可能会发现大号粗体文字警告您不要做什么。在这类文档中，经常会看到大量内容专门用于代码库中特别复杂的部分；公司中会有更多人投入更多时间试图引导读者走上正确的道路，远离他们自己陷入的陷阱。如果您要重构的代码记录在这些来源中并遵循这些模式，那么这可能是可以显著改进的良好证据。考虑一下目标代码文档的理想语气和内容，并以此为灵感。

Maintainers of style guides and onboarding materials can sometimes leave traces of their experiences in the documentation they produce. If they’ve recently made an unexpected discovery about how something works and sought to improve the documentation as a result of that experience, you might be able to catch a glimpse of that in their writing. You might find warnings in large, bolded text of exactly what not to do. It’s also not uncommon to see a disproportionate amount of content devoted to particularly complex pieces of the codebase in these kinds of documents; more people across the company will have devoted more time to trying to steer readers in the right direction, away from the pitfalls they themselves fell into. If the code you want to refactor is documented in these sources and follows these patterns, it might be good evidence that it can be measurably improved. Think about the ideal tone and content of the documentation for your target code and use that as inspiration.

事后分析可以作为很好的支持证据。如果您的团队遵循PagerDuty 事件响应流程并且已经这样做了一段时间，那么您可能会获得数十份事后分析文档，其中详细说明了您的应用程序未按预期运行的每个实例的事件、地点、时间、原因和方式。

Postmortems can serve as great supporting evidence. If your team follows the PagerDuty incident response process and has been doing so for some time, then you likely have access to dozens of postmortem documents detailing the what, where, when, why, and how of every instance where your application wasn’t behaving as expected.

在为值得重构的代码构建案例时，我会搜索事后分析，总结我认为直接涉及该代码的事件。然后我阅读了两个部分：“促成因素”和“什么地方做得不好？”当我怀疑代码的复杂性直接影响了解决问题的时间，甚至可能首先导致了事件发生时，这两个部分可能会证实这一点。列出要重构的区域作为问题的事件数量是一个有价值的指标。

When building a case for code that is worth refactoring, I search for postmortems summarizing incidents I believe directly involved that code. Then I read through two sections: “Contributing Factors” and “What Didn’t Go So Well?” When I suspect that the complexity of the code had a direct impact on the time to resolution or perhaps even caused the incident in the first place, these two sections will likely confirm it. A count of the number of incidents that list the area you want to refactor as a problem makes a valuable metric.

非正式文档

Informal Documentation

除了正式文档外，我们还制作了各种非正式文档。这些是我们认为不是正式文档的书面材料，因为它们通常不以文档形式出现。根据我的经验，我发现非正式来源中的缺陷比任何正式文档都多。

Alongside our formal documentation, we produce a wide range of informal documentation. These are the kinds of written artifacts that we don’t consider to be proper documentation simply because they don’t typically occur in document form. In my experience, I’ve found more speckled throughout informal sources than in any formal documentation.

找到这些资源的关键在于打破思维局限。我在这里列举几个，但请留意您周围的其他资源。您可能会大吃一惊！

Finding these sources is all about thinking outside the box. I’ll enumerate a few here but keep your eyes peeled for other sources around you. You just might surprise yourself!

聊天和电子邮件记录可以提供有关您要重构的代码的深刻信息。最重要的是，这些信息通常可以提供大量背景信息，包括历史和组织信息。例如，假设您想要重构应用程序中异步作业的结构。作业队列系统目前接受一组任意大小的动态参数，以最大限度地提高其使用者的灵活性。不幸的是，这导致了对其实际限制的相当多的困惑，使系统在处理具有极大参数负载的作业时面临内存耗尽的风险，或者在无法解析格式错误的输入时突然崩溃。

Chat and email transcripts can provide insightful information about the code you’re seeking to refactor. Best of all, these often grant a good deal of context, both historical and organizational pieces of information. Say, for instance, you want to refactor how asynchronous jobs are structured in your application. The job queue system currently accepts a dynamic set of arguments of arbitrary size to maximize flexibility for its consumers. Unfortunately, this has led to quite a bit of confusion around its actual limitations, putting the system at risk of running out of memory when processing jobs with extremely large argument payloads, or crashing abruptly when it is unable to parse malformed inputs.

您想确保自己对系统模糊性的体验对您和您的团队来说不是轶事。为了衡量编写新作业的麻烦程度，您在公司的 Slack（或其他消息传递解决方案）中搜索一组与作业队列参数相关的关键字。不出所料，您遇到了许多消息，其中有人对他们的工作没有按预期工作感到惊讶或担心。整个公司的开发人员都在询问他们是否应该提供原始或不透明的 ID。为什么是其中一种而不是另一种？我们要记录这些作业参数吗？如果是，我们是否需要小心包含个人身份信息？我们可以通过这些参数发送多少数据？我们是否能够序列化整个对象并将其提供给作业队列系统？

You want to be certain that your experience with the system’s ambiguity is not anecdotal to you and your team. To measure how troublesome writing new jobs is, you search your company’s Slack (or other messaging solution) for a set of keywords that relate to job queue arguments. Unsurprisingly, you come across a number of messages where someone was surprised or concerned that their job didn’t work as intended. Developers across the company are asking whether they should provide raw or opaque IDs. Why one over the other? Do we log these job arguments? If so, do we need to be careful about including personally identifiable information? How much data can we send via these arguments? Are we able to serialize entire objects and supply these to the job queue system?

您创建一个指向每条消息的文档，并简短描述每条消息的背景。（只需在对话中短暂回滚即可轻松完成此操作。）现在，您可以参考这些实例来说明开发人员当前遇到的困难。

You create a document that points to each of these messages, with a short description of the context around each. (This should be easy to do with a short backscroll through the conversation.) Now you can reference these instances to demonstrate the difficulty that developers are currently running into.

聊天记录让您能够查看您入职前很久的对话。您可能会惊讶地发现，各个工程团队的人都在谈论您入职前几个月或几年急于解决的问题。您可能会遇到其他人定期提出同样的问题。当这种情况发生时，这不仅对您的努力非常有价值，而且您可以通过联系这些团队的人并询问他们对您想要改进的代码的经验来获得一些有价值的盟友。从数量上讲，您可以使用这些对话来估算由于对您想要改进的代码的困惑而损失了多少工程时间并回答有关问题。

Chat history gives you the unique ability to peek into conversations that occurred long before your arrival. You might be surprised to see people spread across a variety of engineering teams talking about the problems you’re eager to fix months or years before your first day on the job. You might encounter others asking the same question at a regular cadence. When this happens, not only is it extremely validating to your endeavor, but you may get some valuable allies by reaching out to the folks on those teams and asking them about their experience with the code you want to improve. Quantitatively, you can use these conversations to approximate how many engineering hours are lost due to confusion about the code you want to improve and answer questions about it.

根据工程团队选择的项目管理工具，您可以通过在错误跟踪系统中搜索相关错误来收集与要重构的代码相关的一些重要指标。您还可以估算其他团队或个人开发人员调查和修复错误或实施与目标代码相关的更改所花费的时间。

Depending on your engineering team’s project management tools of choice, you may be able to gather some important metrics related to the code you want to refactor by searching for related bugs in your bug tracking system. You might also be able to estimate the amount of time other teams or individual developers have spent investigating and fixing bugs or implementing changes related to your target code.

假设某个特定功能或功能集周围的代码随着时间的推移变得越来越复杂。您想投入精力来整理它，以便您的团队能够以更快的速度开发。如果您怀疑团队的速度已经降低，您可以使用项目管理软件来确认这一点。请注意，这是一个非常粗略的指标（与我们所有其他指标一样，仅量化整体问题的一个方面）。您可能需要深入了解您的团队如何组织其开发周期，并自信地删除数据中的异常值，以便能够在此处得出一个令人信服的指标，但对于某些团队来说，这可能是一个无可争议的指标！

Say the code around a particular feature or feature set has been gaining complexity over time. You want to invest effort in tidying it up so that your team can develop at a quicker pace. If you suspect that your team’s velocity has decreased, you can use your project management software to confirm it. Note that this is a very coarse metric (and as with all of our other metrics, only quantifies a single aspect of the overall problem). You will probably need intimate knowledge of how your team organizes its development cycles and confidently remove outliers in your data to be able to tease out a compelling metric here, but for some teams, it can be an indisputable one!

此时，这一切听起来像是量化给定问题的过多调查工作。没关系！由您决定哪些指标对传达问题的严重性和修复问题的潜在好处最有影响。您可能不想或不需要花时间挖掘数百个任务或事后分析，但如果这些信息易于理解和搜索，那么它可能值得。这些指标在试图说服与代码完全无关的管理和领导团队重构是值得的时尤其有用。

At this point, this may all sound like an excessive amount of investigatory work to quantify a given problem. That’s okay! It’s up to you to decide which metrics will have the most impact in communicating the severity of the problem and the potential benefit of fixing it. You may not want or need to spend the time digging through hundreds of tasks or postmortems, but if this information is easy to consume and search, it might be worthwhile. These metrics can especially come in handy when trying to convince management and leadership teams that are highly removed from the code that refactoring is worthwhile.

提交消息

Commit Messages

虽然并非每个人都将编写描述性提交消息作为其开发方法的一部分，但如果您所在的团队中大多数开发人员都这样做，这些简短的描述可以让他们了解可能遇到的问题。我们可以通过搜索一组关键字或隔离与我们感兴趣的一组文件的更改相关的提交消息来识别模式。

Although not everyone makes writing descriptive commit messages part of their development method, if you work on a team where a majority of developers do, these short descriptions can provide a glimpse into the issues that they might be running into. We can identify patterns either by searching for a set of keywords or by isolating commit messages associated with changes to a set of files we’re interested in.

假设我们正在研究之前的作业队列系统问题。我们知道工程师经常在将作业放入队列之前忘记清理他们的参数，从而导致记录个人身份信息 (PII)。我们可以搜索提交消息并识别相应消息中包含“作业”、“作业处理程序”或“PII”等字词的提交。从这个结果集中，我们可能会发现大量提交，这些提交要么引入了导致 PII 泄漏的新作业，要么修复了已经泄漏 PII 的作业。或者，如果我们的作业处理程序方便地组织到不同的文件中，我们可以缩小搜索范围，仅包含对这些文件进行修改的提交，并梳理派生集以查找类似 模式。

Let’s say we’re looking at our job queue system problem from earlier. We know that engineers regularly forget to sanitize their arguments before enqueueing jobs, resulting in logging personally identifiable information (PII). We can search through our commit messages and identify commits where the corresponding messages include words like “job,” “job handler,” or “PII.” From this result set, we might find a substantial set of commits that either introduced a new job responsible for leaking PII or fixed a job already leaking it. Alternatively, if our job handlers are conveniently organized into distinct files, we could narrow our search to include only commits with modifications to these files and comb through the derived set for similar patterns.

一些开发团队通过在提交消息或分支名称中突出显示错误或票号，将他们的提交或变更集与他们的项目管理工具联系起来。如果我们可以获得这些信息，我们可以将变更集链接到我们之前收集的开发速度和错误计数指标。一切都圆满结束了！

Some development teams relate their commits or changesets to their project management tools by highlighting bug or ticket numbers in the commit message or branch name. If this information is available to us, we can link the changeset back to our previous collection of metrics on development velocity and bug count. It all comes full circle!

总体提交

Commits in Aggregate

在他的书《软件设计 X-Rays》中，Adam Tornhill 提出了一套从版本历史中梳理出重要开发模式的技术。他假设这些开发行为可以帮助您确定重构时应优先考虑应用程序的哪些部分，说明某些功能的复杂性如何随时间变化，并突出显示任何紧密耦合的文件或模块。我强烈建议您阅读他的研究，以充分理解这些测量如此具有启发性的心理学原理，但我将在这里总结一些基本技术，以便您在下一次大规模重构之前考虑它们。

In his book, Software Design X-Rays, Adam Tornhill proposes a set of techniques for teasing out important development patterns from version history. He hypothesizes that these development behaviors can help you identify which sections of your application you should prioritize when refactoring, illustrate how the complexity of certain functions have changed over time, and highlight any tightly coupled files or modules. I highly recommend reading his research to comprehend fully the psychology behind why these measurements are so enlightening, but I’ll summarize the basic techniques here so that you might consider them ahead of your next big refactor.

更改频率是指在应用程序的完整版本历史中对每个文件进行的提交次数。您可以通过从提交历史中提取文件名、汇总它们并按频率从高到低的顺序排列它们来轻松生成这些数据点。在实践中，Tornhill 注意到这些频率往往遵循幂分布，其中不成比例的更改发生在一小部分核心文件中。了解最常提交的文件可以让我们准确地知道哪些文件需要最容易让开发人员理解和浏览，因此，从开发人员生产力的角度来看，我们应该花费最多的精力来维护哪些文件。

Change frequencies are the number of commits made to each file over the complete version history of your application. You can easily generate these data points by extracting file names from your commit history, aggregating them, and ordering them from most to least frequent. In practice, Tornhill noticed that these frequencies tended to follow a power distribution, where a disproportionate number of changes occur in a small subset of core files. Knowing the files that are committed to most often tells us exactly which files need to be the easiest to understand and navigate for developers and, therefore, which files we should spend the most effort maintaining, from a developer productivity perspective.

我们可以将相同的更改频率概念应用于文件。通过查看单个提交，我们可以仔细地将更改归因于单个文件中的各个函数，从而为每个函数生成总频率数字。通过将这些数据与我们之前的复杂性指标之一（代码行）相结合，我们可以绘制整个代码库的复杂性随时间的变化。这些信息向我们展示了有待改进的潜在热点。我们可以在完成重构后重新生成这些指标，以确认这些热点的复杂性不仅降低了，而且希望它们的更改频率也降低了。

We can apply the same concept of change frequencies to files as well. By looking at individual commits, we can carefully attribute changes to respective functions within individual files, producing total frequency numbers for each of them. By combining this data with one of our earlier complexity metrics, lines of code, we can map complexity changes over time across the entire codebase. This information shows us potential hotspots ripe for improvement. We can later regenerate these metrics once we’ve completed our refactor to confirm that not only the complexity of these hotspots decreased, but hopefully their change frequency had as well.

Tornhill 还描述了一种通过查看在同一提交中修改的文件集来精确定位程序中紧密耦合的模块的方法。为了描述这个想法，假设我们有三个文件，superheroes.js、supervillains.js和sidekicks.js。在我们的提交的一个子集中，我们有以下更改：提交一修改了superheroes.js和sidekicks.js；提交二修改了所有三个文件；提交三再次修改了superheros.js和sidekicks.js；提交四只涉及superheroes.js 。从表 3-3所示的这个版本历史子集中，我们注意到在四个提交中，其中三个修改了superheroes.js和sidekicks.js。这暗示着这两个文件之间存在某种耦合。当然，并非所有耦合都是坏事（源代码和相应的单元测试文件的更改就是这种情况），但在某些情况下，这些模式可能表明存在错误的抽象、复制粘贴的代码，或者有时两者兼而有之。一旦我们确定了这些问题，我们就可以努力修复它们，然后在稍后重新运行分析以确认它们不再存在。

Tornhill also describes a method for pinpointing tightly coupled modules in your program by looking at sets of files modified within the same commit. To depict this idea, let’s say we have three files, superheroes.js, supervillains.js, and sidekicks.js. In a subset of our commits, we have the following changes: commit one modifies both superheroes.js and sidekicks.js; commit two modifies all three files; commit three again modifies superheros.js and sidekicks.js; and commit four only touches superheroes.js. From this subset of our version history, depicted in Table 3-3, we notice that of four commits, three of them modified both superheroes.js and sidekicks.js. This insinuates that some kind of coupling between these two files exists. Certainly not all coupling is bad (as is the case for changes in source code and the corresponding unit test files), but in some cases these patterns can indicate an erroneous abstraction, copy-pasted code, or sometimes both. Once we’ve pinpointed these problems, we can work to fix them and then rerun the analysis sometime later to confirm that they no longer exist.

与本章中的每个定量指标一样，这种测量也有一些注意事项。不同的开发人员在提交更改方面有不同的做法。一些程序员会进行大量的小提交；其他程序员会进行大量的提交，包括对多个文件的数十次更改，提交到一个变更集中。此外，这种分析很可能会发现一些异常值（配置文件经常更改或自动生成代码中的热点）。我们在仔细研究数据时必须对这些异常保持警惕，以降低在可能不存在的地方发现问题的风险。

As with each of our quantitative metrics in this chapter, there are some caveats to this kind of measurement. Different developers have different practices around committing changes. Some programmers will make a large quantity of tiny commits; others will make large commits, including dozens of changes across multiple files, into a single changeset. Moreover, it’s entirely likely this analysis will reveal some outliers (configuration files frequently changed or hotspots in autogenerated code). We have to be vigilant about these anomalies when poring over the data to mitigate the risk of finding problems where there might not be any.

在路上

On the Road

我们的公路旅行从我们目前居住的蒙特利尔开始。在海岸边散布的数百个城镇中，我们只能选择一个作为目标。因此，经过一番研究，我们决定前往温哥华。

We’re kicking off our roadtrip in Montreal, where we currently live. Of the hundreds of towns and cities speckled along that shore, we have to pick just one to aim for. So, after a bit of research, we decide to aim for Vancouver.

接下来，我们需要熟悉通往市区的高速公路，并决定抵达后可能想住在哪里。我们向住在温哥华或经常去那里的朋友寻求建议。我们来到了耶鲁镇，这是一个以水边的旧仓库建筑而闻名的街区。现在您的旅行有了明确的目的地，我们可以开始弄清楚如何到达那里。

Next, we need to familiarize ourselves with the highways leading directly into the city and decide where we might want to stay upon arrival. We reach out to friends who’ve either lived in Vancouver or who travel there frequently for recommendations. We land on Yaletown, a neighborhood known for its old warehouse buildings by the water. Now that your trip has a well-defined destination, we can start figuring out precisely how to get there.

在上班

At Work

为了说明本章中的许多重要概念，我们将使用一家拥有 15 年历史的生物技术公司的大规模重构示例，我们将其称为 Smart DNA, Inc.。该公司的大多数员工都是研究科学家，为几个存储库中的数百个 Python 脚本组成的复杂数据管道做出贡献。这些脚本部署在五个不同的环境中并在其中执行。所有这些环境都依赖于 Python 2.6 版本。不幸的是，Python 2.6 早已被弃用，导致该公司容易受到安全漏洞的攻击并无法更新重要的依赖项。虽然依赖过时的软件很不方便，但该公司并没有优先升级到较新的 Python 版本。考虑到现有的测试非常有限，这是一项大规模、冒险的任务。简而言之，这是该公司多年来最大的技术债务。

To illustrate the many important concepts in this chapter, we’ll be using an example of a large-scale refactor at a 15-year-old biotechnology company we’ll call Smart DNA, Inc. Most of its employees are research scientists, contributing to a complex data pipeline comprising hundreds of Python scripts across a few repositories. The scripts are deployed to and executed in five distinct environments. All of these environments rely on a version of Python 2.6. Unfortunately, Python 2.6 has long since been deprecated, leaving the company susceptible to security vulnerabilities and preventing it from updating important dependencies. While relying on outdated software is inconvenient, the company has not prioritized upgrading to a newer Python version. It’s a massive, risky undertaking, given the very limited testing in place. Simply put, this was the biggest piece of technical debt at the company for many years.

研究团队最近越来越担心无法使用较新版本的核心库。鉴于升级对业务来说非常重要，我们已着手研究如何将每个存储库和环境迁移到 Python 2.7。

The research team has recently grown concerned about its inability to use newer versions of core libraries. Given that the upgrade is now important to the business, we’ve been tasked with figuring out how to migrate each of the repositories and environments to use Python 2.7.

研究团队使用 来管理依赖项pip。每个存储库都有自己的依赖项列表，这些依赖项都编码在requirements.txt中。由于这些不同的 requirements.txt文件，团队在切换项目时很难记住给定项目上安装了哪些依赖项。这还需要软件团队审核每个文件并单独升级以与 Python 2.7 兼容。因此，软件团队决定，虽然这不是必需的，但统一存储库并因此统一依赖项可以让他们更轻松地升级 Python 2.7（并简化研究人员的开发过程 ）。

The research team manages its dependencies by using pip. Each repository has its own list of dependencies, encoded in a requirements.txt. Having these distinct requirements.txt files has made it difficult for the team to remember which dependencies are installed on a given project when switching between projects. It also would require the software team to audit each file and upgrade it to be compatible with Python 2.7 independently. As a result, the software team decided that although it was not necessary, it would make the Python 2.7 upgrade easier for them (and simplify the researchers’ development process) to unify the repositories and thus unify the dependencies.

我们的执行计划应明确列出所有起始指标和目标结束指标，并附加一个可选但有用的附加列来记录实际观察到的结束状态。对于 Python 迁移，起始指标集很明确：每个存储库都有一个不同的依赖项列表，每个环境都运行 Python 2.6。所需的指标集同样简单：让每个业务环境都运行 Python 2.7，并在一个地方管理一组清晰、简洁的必需库。表 4-1显示了我们列出 Smart DNA 指标的示例。

Our execution plan should clearly outline all starting metrics and target end metrics, with an optional, albeit helpful, additional column to record the actual, observed end state. For the Python migration, the starting set of metrics was clear: each repository had a distinct list of dependencies, with each environment running Python 2.6. The desired set of metrics was equally simple: have each of the business’s environments running Python 2.7, with a clear, succinct set of required libraries managed in a single place. Table 4-1 shows an example where we’ve listed Smart DNA’s metrics.

在路上

On the Road

因此，对于我们的公路旅行，我们快速搜索了一下，看看蒙特利尔和温哥华之间最直接的路线是什么样的（图 4-1）。假设交通状况最差，如果我们从蒙特利尔出发，不间断地向西行驶，似乎需要 47 个小时。

So, for our roadtrip, we do a quick search to see what the most direct route between Montreal and Vancouver looks like (Figure 4-1). Presuming minimal traffic, it appears to take 47 hours if we were to leave Montreal and drive nonstop westward.

图 4-1.我们在蒙特利尔的地址和温哥华耶鲁镇社区之间的最直接路线

我们可以通过确定每天适合驾驶几个小时，并将这段时间平均分配到大约 47 个小时来确定更合理的行程下限。如果我们想花 8 个小时开车，那就需要大约 6 天的时间。

We can determine a more reasonable lower bound for our trip by deciding how many hours we’re comfortable driving per day and splitting that up evenly over the approximate 47 hours. If we want to commit to eight hours of driving, it’ll take us just about six days.

现在我们已经绘制了两点之间的最短路径，我们可以开始找出我们想要改变的主要复杂因素或总体策略。直接路线的一个特点是，它的大部分路程穿越美国，而不是加拿大。如果我们想将我们的行程限制在北纬 49 度以北的地区，我们将在旅途中增加一两个小时。然而，因为它确实降低了旅行的整体复杂性（不需要携带护照或担心在过境时浪费时间），我们将选择留在加拿大（图 4-2）。

Now that we’ve mapped the shortest possible path between the two points, we can start to pick out any major complications or overarching strategies we want to change. One peculiarity of the direct route is that the vast majority of it travels across the United States, not Canada. If we want to restrict our drive to the area north of the 49th parallel, we’d be adding an extra hour or two to the trip. However, because it does reduce the overall complexity of the trip (no need to carry our passport or worry about time wasted at a border crossing), we’ll opt to stay in Canada (Figure 4-2).

图 4-2一条速度稍慢的路线，仅限于加拿大道路

在上班

At Work

不幸的是，用于软件项目的 Google 地图尚未问世。那么我们如何确定从现在到项目完成的最短路径呢？我们可以通过以下几种方式来实现：

Unfortunately, Google Maps for software projects doesn’t exist quite yet. So how do we determine the shortest path from now to project completion? We can do this in a couple of ways:

• 打开一个空白文档，花 15 到 20 分钟（或者直到你想不出为止）写下你能想到的每个步骤。将文档放在一边至少几个小时（最好是一两天），然后再次打开它并尝试按时间顺序排列每个步骤。当你开始对步骤进行排序时，继续问自己是否每个步骤都是实现最终目标所绝对需要的。如果不是，请将其删除。一旦你有了一组有序的步骤，请重新阅读该过程。填补出现的任何明显空白。如果任何步骤定义非常不明确，请不要担心；目标只是提供完成项目所需的最少步骤。这不会是最终产品。

• Open a blank document and for 15 to 20 minutes (or until you’ve run out of ideas), write down every step you can come up with. Set the document aside for at the very least a few hours (ideally a day or two), then open it up again and try to order each step in chronological order. As you begin to order the steps, continue to ask yourself whether each is absolutely required to reach the final goal. If not, remove it. Once you have an ordered set of steps, reread the procedure. Fill in any glaring gaps as they arise. Don’t worry if any steps are terribly ill-defined; the goal is only to produce the minimum set of steps required to complete your project. This won’t be the final product.

• 召集几个对项目感兴趣或你知道他们会做出贡献的同事。留出一个小时左右的时间。为你们每个人准备一包便签和一支笔。在 15 到 20 分钟内（或直到每个人的笔都放下），写下你认为需要的每个步骤，每个步骤都写在单独的便签上。然后，让第一个人按时间顺序列出他们的步骤。随后的队友查看他们自己的每张便签，并将其与副本配对或将其插入时间线内的适当位置。一旦每个人都整理好所有笔记，就查看每个步骤，并询问房间里的人是否认为该步骤对于实现目标绝对必要。如果不是，就丢弃它。最终产品应该是一组合理的最小步骤。（你可以轻松地将此方法应用于分布式团队，方法是将所有单独集思广益的步骤合并到共同共享的文档中。无论哪种方式，练习的最终输出都应该是一份易于分发和协作改进的书面文件。）

• Gather a few coworkers who are either interested in the project or you know will be contributing. Set aside an hour or so. Grab a pack of sticky notes and a pen for each of you. For 15 to 20 minutes (or until everyone’s pens are down), write down every step you think is required, each on individual sticky notes. Then, have a first person lay out their steps in chronological order. Subsequent teammates go through each of their own sticky notes and either pair them up with their duplicates or insert them into the appropriate spot within the timeline. Once everyone’s organized all of their notes, go through each step and ask the room whether they believe that the step is absolutely required in order to reach the goal. If not, discard it. The final product should be a reasonable set of minimal steps. (You can easily adapt this method for distributed teams by combining all individually brainstormed steps into a jointly shared document. Either way, the final output of the exercise should be a written document that is easy to distribute and collaboratively improve.)

如果这两种方法都不适合您，那也没关系！使用您认为最有效的任何方法。只要您能够列出您认为可以实现目标的直接途径的步骤列表，无论这些步骤定义得多么模糊，您都已成功完成了这一关键步骤。

If neither of these options works for you, that’s all right! Use whatever method you find most effective. As long as you are able to produce a list of steps you believe model a direct path to achieving your goal, no matter how ill-defined they might be, you’ve successfully completed this critical step.

Smart DNA 团队在会议室里花了几个小时集思广益，想出了使用新版 Python 来获取所有服务所需的步骤。他们在白板上画了一条时间线。最左边是他们的起点，最右边是他们的目标。团队成员轮流列出沿途的重要步骤，并将它们按顺序排列。集思广益得出的部分步骤如下：

The team at Smart DNA gathered into a conference room for a few hours to brainstorm the steps required to get all services using a newer version of Python. On a whiteboard, they started out by drawing a timeline. On the far left was their starting point and, on the far right, their goal. Teammates alternated listing important steps along the way, slotting them in along the line. A subset of the brainstormed steps are as follows:

• 手动构建每个存储库中所有包的单一列表。

• Build a single list of all the packages across each of the repositories manually.

• 将列表缩小到仅包含必要的包。

• Narrow the list to just the necessary packages.

• 确定在 Python 2.7 中每个包应该升级到哪个版本。

• Identify which version each package should be upgraded to in Python 2.7.

• 使用所有必需的包构建一个 Docker 容器。

• Build a Docker container with all the required packages.

• 在每个环境上测试 Docker 容器。

• Test the Docker container on each of the environments.

• 为每个存储库找到测试；确定哪些测试是可靠的。

• Locate tests for each repository; determine which tests are reliable.

• 将所有存储库合并为一个存储库。

• Merge all the repositories into a single repository.

• 选择一个 linter 和相应的配置。

• Choose a linter and corresponding configuration.

• 将 linter 集成到持续集成中。

• Integrate the linter into continuous integration.

• 使用 linter 来识别代码中的问题（未定义的变量、语法错误等）。

• Use the linter to identify problems in the code (undefined variables, syntax errors, etc.).

• 修复 linter 发现的问题。

• Fix problems the linter identified.

• 在所有环境上安装 Python 2.7.1 并测试。

• Install Python 2.7.1 on all environments and test.

• 在低风险脚本子集上使用 Python 2.7。

• Use Python 2.7 on a subset of low-risk scripts.

• 将 Python 2.7 推广到所有脚本。

• Roll out Python 2.7 to all scripts.

从我们的子集中我们可以看出，有些可以并行化或重新排序，而其他的则应该进一步细分。在这个过程的这个阶段，我们的重点是大致了解所涉及的步骤；我们将在整个章节中完善这个过程。

We can see from our subset that some can be parallelized, or reordered, and others should be broken down into further detail. At this point in the process, our focus is on getting a rough sense of the steps involved; we’ll refine the process throughout the chapter.

在路上

On the Road

在温尼伯和温哥​​华之间的这段旅程中，我们向一些朋友和家人询问了值得游览的景点和值得做的事情。在权衡了他们的建议和我们自己的兴趣之后，我们制定了一个粗略的行程，其中包括从露营到参观博物馆、品尝美味佳肴以及几次拜访大家庭的一切（图 4-3）。但这些景点从未让我们偏离路线。

For the stretch of the trip between Winnipeg and Vancouver, we ask some friends and family for recommendations of sights to see and things to do. After weighing their suggestions with our own interests, we come up with a rough itinerary, which includes everything from camping to museum visits, tasty pitstops, and a few visits to extended family (Figure 4-3). But at no point do any of these points of interest take us radically off course.

图 4-3我们的大致行程

在上班

At Work

我们可以采用类似的策略来缩小重构工作的里程碑。对于我们之前集思广益的每个步骤，我们可以问自己这些 问题：

We can apply similar tactics to narrow in on our milestones for our refactoring effort. For each of the steps we brainstormed previously, we can ask ourselves these questions:

暗模式/亮模式

Dark Mode/Light Mode

我们可以采用我们在 Slack 中创造的明暗技术来比较重构前和重构后的行为。它的工作原理如下。

We can compare pre-refactor and post-refactor behavior by employing what we’ve coined at Slack as the light/dark technique. Here’s how it works.

首先，将重构后的逻辑与当前逻辑分开实现。示例 4-1以小规模描述了此步骤。

First, implement the refactored logic separately from the current logic. Example 4-1 depicts this step on a small scale.

// Linear search; this is the old implementation
function search(name, alphabeticalNames) {
  for(let i = 0; i < alphabeticalNames.length; i++) {
    if (alphabeticalNames[i] == name) return i;
  }
  return -1;
}

// Binary search; this is the new implementation
function searchFaster(name, alphabeticalNames) {
  let startIndex = 0;
  let endIndex = alphabeticalNames.length - 1;

  while (startIndex <= endIndex) {
    let middleIndex = Math.floor((startIndex+endIndex)/2);
    if (alphabeticalNames[middleIndex] == name) return middleIndex;

    if (alphabeticalNames[middleIndex] > name) {
      endIndex = middleIndex - 1;
    } else if (alphabeticalNames[middleIndex] < name) {
      startIndex = middleIndex + 1;
    }
  }

  return -1;
}

// Linear search; this is the old implementation
function search(name, alphabeticalNames) {
  for(let i = 0; i < alphabeticalNames.length; i++) {
    if (alphabeticalNames[i] == name) return i;
  }
  return -1;
}

// Binary search; this is the new implementation
function searchFaster(name, alphabeticalNames) {
  let startIndex = 0;
  let endIndex = alphabeticalNames.length - 1;

  while (startIndex <= endIndex) {
    let middleIndex = Math.floor((startIndex+endIndex)/2);
    if (alphabeticalNames[middleIndex] == name) return middleIndex;

    if (alphabeticalNames[middleIndex] > name) {
      endIndex = middleIndex - 1;
    } else if (alphabeticalNames[middleIndex] < name) {
      startIndex = middleIndex + 1;
    }
  }

  return -1;
}

然后，如示例 4-2所示，将逻辑从当前实现重新定位到单独的函数。

Then, as shown in Example 4-2, relocate the logic from the current implementation to a separate function.

// Existing function now calls into relocated implementation
function search(name, alphabeticalNames) {
  return searchOld(name, alphabeticalNames);
}

// Linear search logic moved to a new function.
function searchOld(name, alphabeticalNames) {
  for(let i = 0; i < alphabeticalNames.length; i++) {
    if (alphabeticalNames[i] == name) return i;
  }
  return -1;
}

// Binary search; this is the new implementation
function searchFaster(name, alphabeticalNames) {
  let startIndex = 0;
  let endIndex = alphabeticalNames.length - 1;

  while (startIndex <= endIndex) {
    let middleIndex = Math.floor((startIndex+endIndex)/2);
    if (alphabeticalNames[middleIndex] == name) return middleIndex;

    if (alphabeticalNames[middleIndex] > name) {
      endIndex = middleIndex - 1;
    } else if (alphabeticalNames[middleIndex] < name) {
      startIndex = middleIndex + 1;
    }
  }

  return -1;
}

// Existing function now calls into relocated implementation
function search(name, alphabeticalNames) {
  return searchOld(name, alphabeticalNames);
}

// Linear search logic moved to a new function.
function searchOld(name, alphabeticalNames) {
  for(let i = 0; i < alphabeticalNames.length; i++) {
    if (alphabeticalNames[i] == name) return i;
  }
  return -1;
}

// Binary search; this is the new implementation
function searchFaster(name, alphabeticalNames) {
  let startIndex = 0;
  let endIndex = alphabeticalNames.length - 1;

  while (startIndex <= endIndex) {
    let middleIndex = Math.floor((startIndex+endIndex)/2);
    if (alphabeticalNames[middleIndex] == name) return middleIndex;

    if (alphabeticalNames[middleIndex] > name) {
      endIndex = middleIndex - 1;
    } else if (alphabeticalNames[middleIndex] < name) {
      startIndex = middleIndex + 1;
    }
  }

  return -1;
}